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Introduction 


NAV Ill 


Proton Base URL 


https://[ sandbox ][api].hydrogenplatform.com/proton/v1 


e 
All client facing no-code apps utilize Proton APIs in a pre-approved, compliant manner, but these APIs can be 
used standalone in select enterprise use-cases. 


The Hydrogen Proton API is designed for added business logic on top of the core Nucleus data model within 
Hydrogen. Proton offers analytical tools, scoring, recommendations, and simulations. 


> Run in Postman 


Authentication 


All Hydrogen APIs use the same OAuth 2.0 authorization. Please refer to the Nucleus API for detailed 
documentation. 


Client Credentials 


If you are utilizing the Integration client libraries for client credentials authorization, please view the 
sample code in the language of your choice in the right panel. 


Resource Owner Password Credentials 
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If you are utilizing the client libraries for password authorization, please view the sample code in the 
language of your choice in the right panel. 


Fields 


IDs 


IDs are represented in universally unique identifier (UUID) format. A UUID is a string of 32 alphanumeric 


characters in the format 8-4-4-4-12. An example would be efa289b2-3565-42e6-850b-8dad25727e99 . All 


requests that reference Nucleus data entities must utilize this UUID format. 


DATES 


Dates are represented in ISO-8601 format, as YYYY-MM-DD. An example would be 2018-01-10. 


Errors 


ERROR CODES 
Code Description 
400 Bad Request. 
401 Unauthorized. Occurs when you are using an invalid or expired access token. 
403 Forbidden. The request was valid but you are not authorized to access the resource. 
404 Not Found. Occurs when you are requesting a resource which doesn't exist such as an incorrect 
URL or incorrect ID. 
429 Too Many Requests. Exceeded the rate limit set. Currently, there is no rate limit on the APIs. 
500 Internal Server Error. 
503 Service Unavailable. If the API is down for maintenance you will see this error. 
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= STATUS CODES 
Code Description 
200 


Versioning 


Hydrogen Proton API Reference 


Ok. The request was successful. 


The Proton API is currently in major version 1.0. All features which are not backwards compatible will be 


pushed as a major version release. Features that we consider to be backwards compatible include the 


following: 


e Adding new API resources 


e Adding new optional request parameters to existing API methods 


e Adding new fields to existing API responses 


e Changing the order of fields in existing API responses 


e Changing the length or format of objects 


Changelog 


Changes and updated versions will be outlined here. 


Date 


2021- 
06-07 


2021- 
06-07 


Change 


update 


addition 


Description 


Enabled support for household-level and business-level analytics to various 
services. Introduced anew transaction_status_scope parameter to improve 
analytics granularity for transaction-based services. Expanded functionality for Card 
Authorization. Improved periodicity handling in Budget Calculator. Enabled new 
functionality in Recurring Transaction Analysis to flag transaction records that are 
identified as recurring. Improved error handling for the Cards module. Fixed various 
divide-by-zero errors. Fixed a bug in Cash Flow Analysis that led to incorrect 
transactions being included in the analysis for certain requests. 


Added the Spending Analysis service to the Personal Financial Management 
module. Added the Card Analysis service to the Cards module. Added the 
Performance Calculator and Decision Tree Result services to the Wealth module. 
Added the Order Rebalance service to the Portfolio Management module. 
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2020- 
12-31 


2020- 
09-30 


2020- 
03-04 


2020- 
02-14 


Change 


addition 


addition 


update 


update 


Hydrogen Proton API Reference 


Description 


Added a Cards module with two new services: Card Authorization and Card Limit 
Check. Added support for currency_conversion across various services. Also 
added Integrations support for services that consume market data via the 
market_data_source parameter. Budget Calculator and Cash Flow Analysis now 
support both held and held-away account data via the scope parameter. Added 
functionality to Budget Calculator to calculate average historical spending across 
budget categories. Added an only_cleansed parameter to services that consume 
Portfolio Transactions. Standardized the handling of boolean input parameters to 
minimize ambiguity. Fixed several bugs in the processing of proxy security data 
across applicable services. 


Added two services to the Personal Financial Management module: Fee Analysis 
and Recurring Transaction Analysis. 


Relaxed constraints on underlying data in Financial Picture by treating a lack of 
balance records with non-zero balances as 0 net worth. Enhanced error messaging 
for Goal Accumulation Allocation when underlying security price data is insufficient. 
Added more descriptive error messaging when a Proton request fails due to an 
issue with another Hydrogen product such as Nucleus API or Integration API. 
Improved input validation on the opt_config object and more descriptive error 
messaging when passing it empty strings as tickers for the following endpoints: 
Goal Accumulation Allocation, Goal Decumulation Allocation, Risk Allocation, 
Portfolio Optimization Score. Updates to Budget Calculator: Changed as_of_date 
to use UTC instead of the local current date. Fixed issues where 
aggregation_accounts was not properly considered and where spending was 
not accurately reflected on budgets with a frequency unit of daily. Relaxed 
constraints on underlying data by treating a lack of valid transaction records for a 
budget as 0 spending. Enhanced results for a budget with a null subcategory 
so that it will consider all transactions that map at the category level. Improved 
error handling when passing an invalid budget id. 


Made initial balance parameter optional with a default value of O for the 
following endpoints: Annuity Calculator, Education Calculator, Savings Calculator, 
Variable Annuity. Nucleus entity connected to Goal Accumulation Allocation and 
Goal Decumulation Allocation endpoints. Updated Risk Allocation to make the 
risk score parameter optional with a default value of 50, enhance input 
validation and error messaging, and fix a bug that prevented the 0-100 range on 
this parameter from being enforced. Upgraded the proxy data framework when 
use proxy data is true for various services. Improved error messaging for 
Goals and Risk Scoring when sourcing data from Nucleus, and for Goal 
Decumulation when there is an invalid periodicity relationship between 


withdrawal config amounts and the goal horizon. Fixed a series of bugs: 
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2019- 
12-19 


2019- 
08-22 


2019- 
08-22 


2019- 
08-22 


Change 


update 


update 


update 


addition 
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Description 


Allowed a result_type of custom to be accurately reflected in the results for 
Variable Annuity. Updated Risk Allocation to prevent the allocations input from 
being enforced as conditionally required. Adjusted Life Insurance Needs Calculator 
to allow optional inputs to have their default values properly set. Changed Goal 
Accumulation services to prevent certain nested inputs in the 
recommendation_config field from being required and to properly process 
deposit_config period references for certain combinations of deposit frequency 
and goal horizon frequency. Changed Goal Decumulation services to produce the 
proper error message when d_horizon has a value of 0 and to allow for 
successful analysis in some cases when a_horizon has a value of 0. 


Nucleus data entities connected to Goals, Simulations, and Financial Planning. 
Audit log functionality added to Goals and Simulations using the parameter 


create_log in request parameter. 


Fixed a series of bugs: Enabled Financial Health Check to properly handle cases 
where the ratio denominator is 0. Updated Sensitivity Analysis & Scenario Analysis 
to manually override t-stat to None/null when it comes back as NaN. Updated 
Education Calculator & Retirement Calculator to prevent excess cash to be left in 
deposit_schedule atthe end of the time horizon when an inflation rate was 
applied. Changed the order of fields in return_details within Annuity Calculator 
to be consistent with other endpoints, additionally, fixed a bug that sometimes 
prevented a successful analysis. Changed lag parameter in Sensitivity Analysis to 
be optional and default to 0. Finally, updated select error responses to be in proper 
JSON format. 


Updated Emergency Fund Calculator to remove a restriction from the 
interest_rate parameter. Updated Savings Calculator to remove the constraint 
on the length of the return_schedule array. Added a series of new parameters to 
the Monte Carlo simulation. Added use_proxy_data to the following endpoints 
Mean-Variance Optimization, Event Study, Sensitivity Analysis, Scenario Analysis, 
Portfolio What If, Diversification Score, Portfolio Optimization Score, Goal 
Decumulation, Goal Accumulation, Risk Allocation, Variable Annuity. Added new 
response fields to the Financial Planning and Annuity Calculators to better 
summarize the output. 


Added three new services to the Personal Financial Management module: Budget 
Calculator, Cash Flow Analysis, and Financial Picture. The Cash Flow Analysis Tool 
displays trends related to the users spending and cash flow, allowing them to 
determine where they can cut down their spending and save money. The Financial 
Picture Tool runs analytics on all held-away accounts that have been aggregated so 
that the user may see a total picture of their financial life. The Budget Calculator 
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2019- 
03-26 


2019- 
03-26 


2019- 
03-26 


2019- 
01-24 


2018- 


12-07 


2018- 
12-07 


2018- 
11-12 


Change 


update 


update 


addition 


update 


update 


addition 


addition 


Hydrogen Proton API Reference 


Description 


pulls in the user’s spending and budget information from Nucleus, which is then 
used to generate insightful information about their budget by category and 
merchant. Finally, we added an additional service to the Annuities module: Variable 
Annuity; this service helps to evaluate potential outcomes and get a better 
understanding of how a variable annuity product may behave. 


Fixed a bug in which certain Backtest requests would fail based on fluctuating 
model securities. Fixed a bug in which the impact of inflation was reflected 
inconsistently across Financial Planning calculators. Fixed a bug in which rates of 
return were incorrectly annualized in Portfolio Optimization Score. Fixed a bug in 
which the Mean-Variance Optimization service would not return frontier portfolios 
when one frontier point encountered an error. Fixed a bug in which Mean-Variance 
Optimization would fail based on the absence of optional security asset class data. 
Fixed a bug in which the arithmetic mean return was used instead of the geometric 
mean in Goals allocation services. 


Introduced two new parameters to all services in the Goals module, 
adjust for compounding and compounding rate , which help to approximate a 
compounding effect on deposits for specific request configurations. 


Added three new services to the Simulations module: Sensitivity Analysis, Scenario 
Analysis, and Portfolio What-If. These tools offer the ability to better understand an 
investment portfolio by simulating its behavior under a variety of circumstances. 
The former two services simulate the impact of external changes, while the latter 
considers changes within the portfolio itself. 


Fixed a bug in the Goals module in which portfolio risk was improperly calculated 
when converting between certain time frequencies. Added handling for Mortgage 
Calculator cases in which down payment could be negative. 


Included new response fields for the Backtest service to summarize the risk and 
return of the backtested model. 


Added the Event Study service to the Simulations module, which simulates a 
portfolio's behavior during key historical events. Added the Financial Health Check 
Service to the Financial Health module, which offers the ability to assess an 
individual's status through a series of financial ratios. 


Added two services to the Financial Health module: Portfolio Optimization Score, 
which evaluates a portfolio against its optimal counterpart, and Diversification 
Score, which assesses the level of diversification found in an investor's portfolio. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


6/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


Date Change Description 
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Added an Annuity module with five Annuity Calculator services for the analysis of 
fixed annuity streams. 


2018- update Enhanced all services in the Goals module, making the framework more robust by 
08-08 allowing for greater levels of customization and the ability to handle a wider array of 
goal configurations. 


2018- addition Added a suite of financial calculators, including Education, Mortgage, Life Insurance 
07-02 Needs, Major Purchase, Retirement, and Savings. 


Terminology 


Throughout this documentation, there will be a number of financial terms and concepts that may be confusing 
to the developer not privy to financial jargon. After first outlining basic platform terms, we have defined some 
financial terms that may be referred to or represented in the parameters or their descriptions. 


Nucleus Terms 


Name Description 


Client A client is identified based on a unique identifier, usually a government issued ID (e.g. 
social security number). A client can have multiple cards, accounts, aggregation 
accounts, budgets, models, allocations and goals. 


Household A household is a grouping of clients in the same family, which can be used to view their 
finances aggregated across the household. 


Business A business represents a corporate entity where collections of clients are employed. A 
client may be designated as the owner of a business. 


Contact A contact represents a company that purchases goods or services from a business 
(customer), or a company that supplies good or services to a business (supplier). 
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Invoice 


Financial 


Statement 


Card 


Card Program 


Spending 
Control 


Aggregation 
Account 


Budget 


Goal 


Allocation 


Model 


Account 


Portfolio 
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Description 


An invoice represents an account receivable owed by a customer to a business 
(invoice), or an account payable owed by a business to a supplier (bill). 


A financial statement represents statistics about a business generated via financials 
such as an income statement and balance sheet. 


A card can be issued to a client via a card program manager. 


A card program is issued and run by a program manager who is responsible for 
establishing relationships with processors, sponsor banks, and card networks. 


A spending control can be added at a client level for all cards associated with the client. 
These controls will restrict purchases and ATM withdrawal amounts, as well as spending 
within a category or at a specific merchant or location. 


A client can have one or more aggregation accounts. These accounts are external, 
meaning they are held-away at various other institutions, and they may have balances, 
transactions, and/or holdings associated with them. 


A budget allows a client to track their spending on a card, account, or aggregation 
account(s) against their budget over time. 


A desired financial outcome in the future, defined by time and monetary value. 


An abstract collection of one or more models grouped together and strategically 
weighted. Each account is assigned to one allocation, which can contain multiple 
models. 


An abstract collection of one or more securities grouped together and strategically 
weighted. An account can be subscribed to n-number of models through an allocation. 
Each model holds n-number of securities and may be a component of n-number of 
allocations. 


A client can have one or more accounts and each account can be assigned to one 
allocation. An account can hold n-number of portfolios. 


Portfolios are unique to a given account, while models have holdings with theoretical 
strategic weights; portfolios reflect actual account holdings, which depend on changes in 
the model, account additions and withdrawals, dividends, canceled trades, and other 
account-specific activity. Portfolios may or may not be subscribed to a model, which can 
be a component of an allocation. 
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Asset Size 


Hydrogen Proton API Reference 


Description 


A security is defined as any financial instrument or product that an investor may own. 
Securities have certain attributes, like prices and unique identifiers. Securities are held 
within models and portfolios. 


The aggregate monetary value of an investment account based on underlying positions. 
The asset size changes as securities fluctuate or monies/securities are 
deposited/withdrawn. 


Investing Terms 


Name 


Accumulation 


Confidence 
Target 


Decumulation 


Drift-Based 


Rebalancing 


Efficient Frontier 


Goal Horizon 


Monte Carlo 


Description 


Accumulation goals are defined by a target amount of capital in the future, assumed 
to be redeemed in full upon termination of the goal horizon. 


Confidence targets, indicated by conf tgt when applicable, serve as the basis for 
a percentile analysis of Monte Carlo outcomes, in which outcomes below the ((1 — 
c)*100)th percentile, where c is the confidence target on a scale from 0 to 1, are 
excluded as a left-tail margin. If the confidence target is not satisfied, this is reflected 
by a goal probability that is less than the confidence target. 


Decumulation goals are defined by redeeming a target amount of capital periodically 


over a horizon, and may also include an accumulation phase. 


Drift-based rebalancing generates a signal whenever a portfolio holding deviates 
from its strategic target by a predefined amount. 


An efficient frontier is a collection of optimal portfolios across a maximal range of risk 
and return levels. 


The amount of time until the funds are needed for a given goal. A goal may have a 
decumulation horizon as well as an accumulation horizon. 


Using a random walk, this process estimates future values by simulating individual 
periods of portfolio growth based on samples derived from the given risk and return 
portfolio attributes, in conjunction with ongoing cash inflows or outflows (which occur 
at the end of each period) in the simulated account. 
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Name Description 
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Optimization A programmatic mathematical process by which securities are weighted to optimally 
achieve an objective. 


Percentage Throughout the API, percentages are represented in decimal format. For example, 
0.02 translates to 2%. 


Rebalance Execute trades in an account in order to move holdings in line with the model or 
allocation strategic weights. 


Tax (Principal Principal_tax and nonprincipal_tax refer to an expected tax rate paid on the 

and Non- redemption of principal funds (e.g. contributed capital) and non-principal funds (e.g. 
Principal) gains/profits). 

Ticker The unique identifier of a given security. Unlike a CUSIP, this is a string of letters 


usually five characters or less. 


Universe The pool of securities that are acceptable to select for a given model, allocation or 
portfolio. 


Cards 


Card Analysis 


Card Analysis provides a top-down view of card spending activity. Data may be analyzed at the client, 
business, card program, or tenant level. The analysis gives insight into top spenders, top cards, metrics such 
as average transaction size, and a historical view to see how card activity changes over time. 


HTTP REQUEST 


POST /card_analysis 


Example Request 
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curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


"card program id": "48f67eea-0ae6-4396-add7-65f57c515367", 
"currency code": "USD", 

"start date": "2021-03-01", 

"end date": "2021-05-11", 

"card status scope": [ 


"activated" 


Jo 


"transaction status scope": | 


"completed", 
"pending" 


IF 


"response limit": 1, 


"history frequency interval": "month", 


"show history": true, 


"show top cardholders": true, 


"show top cards": true 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/card analysis" 


ARGUMENTS 


Parameter 


client id 
UUID 


business id 
UUID 


card program id 
UUID 


currency code 


string 


Description 


The ID of a Nucleus Client to analyze. If provided, all cards linked to 

this client will be considered. If one of client id, business id or 
card program id is not passed, all clients within the tenant will be 

considered. 


The ID of a Nucleus Business to analyze. If provided, all clients linked 
to this business will be considered. If one of client id, 
business id or card program id is not passed, all clients within 
the tenant will be considered. 


The ID of a Nucleus Card Program to analyze. If provided, all clients 
linked to this card program will be considered. If one of client id, 
business id or card program id is not passed, all clients within 


the tenant will be considered. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Only records with this currency code will be considered. 


Defaults to USD if currency conversion is not provided. If 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 11/440 


8/3/23, 5:08 PM 


zi 
z 


Parameter 


currency conversion 
string 


start date 
date 


end date 
date 


card status scope 


array[string] 


transaction status scope 


array[string] 


response limit 


integer 


history frequency interval 


string 


show history 


boolean 


show top cardholders 


boolean 


show top cards 


boolean 
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Description 


currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Records will be converted from their original currency to 
the one indicated here. Conversions are supported both to and from 
the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


Start date of the analysis period. Defaults to the earliest date of 
available cardholder spending data. 


End date of the analysis period. Defaults to today's date. 


If populated, only Nucleus Cards whose status matches one of the 
array values are considered in the analysis. Defaults to null, 
meaning transaction data from all cards are considered regardless of 
the status. 


If populated, only Nucleus Portfolio Transactions whose status 
matches one of the array values are considered in the analysis. 
Defaults to nu11 , meaning all transactions are considered regardless 
of the status. 


Maximum number of records to be returned in top businesses, 


top cardholders , and top cards. Defaults to 10. 


The frequency of historical cardholder spending data. Value may be 


day, week, month, quarter, or year. Defaults to month. 


If true, returns a history of spending, in total, by business, by 
cardholder, and by card. Defaults to false. 


If true, returns details on the top spending cardholders. Defaults to 
false. 


If true, returns details on the top spending cards. Defaults to false. 
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"currency code": "USD", 
"analysis start": "2021-03-01", 
"analysis end": "2021-05-11", 
"summary": { 
"number of cardholders": 5, 
"number of cards": 5, 
"total amount spent": 1925.0, 
"number of transactions": 6, 
"mean transaction amount": 320.83, 
"history": [ 
{ 
"period start": "2021-03-01", 
"period end": "2021-03-31", 
"amount spent": 125.0 


bo 
{ 
"period start": "2021-04-01", 
"period end": "2021-04-30", 
"amount spent": 1800.0 
ko 
{ 
"period start": "2021-05-01", 
"period end": "2021-05-11", 
"amount spent": 0.0 
3 
] 
bo 
"top cardholders": | 
{ 
"name": "Crystal Jennings", 


"number of cards": 1, 

"total amount spent": 750.0, 

"number of transactions": 1, 

"mean transaction amount": 750.0, 

"history": [ 

{ 

"period start": "2021-03-01", 
"period end": "2021-03-31", 
"amount spent": 0.0 


D 
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"period start": "2021-04-01", 


z "period_end": "2021-04-30", 
z "amount spent": 750.0 
bo 
{ 
"period start": "2021-05-01", 
"period end": "2021-05-11", 
"amount spent": 0.0 
} 
] 
} 
], 
"top cards": [ 
{ 
"card holder name": "Crystal A Jennings", 
"institution name": "Hydro Bank", 
"card name": "Select Debit Card", 
"total amount spent": 750.0, 
"number of transactions": 1, 
"mean transaction amount": 750.0, 
"history": [ 
d 
"period start": "2021-03-01", 
"period end": "2021-03-31", 
"amount spent": 0.0 
bo 
{ 
"period start": "2021-04-01", 
"period end": "2021-04-30", 
"amount spent": 750.0 
bo 
{ 
"period start": "2021-05-01", 
"period end": "2021-05-11", 
"amount spent": 0.0 
} 
] 
} 
] 
} 
RESPONSE 
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currency_code 


analysis start 


analysis end 


summary 


number_of_cardholders 


number_of_cards 


total amount spent 


number of transactions 


mean transaction amount 


history 


period start 


period end 


amount spent 


top cardholders 


name 


number of cards 


total amount spent 


number of transactions 
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Description 


Currency code associated with monetary response values. 


Start date of the analysis period. If start date was provided in the 
request, it is reflected here. If start date was not provided, this 
value is derived dynamically. 


End date of the analysis period. If end date was provided in the 
request, it is reflected here. If end date was not provided, this value 
is derived dynamically. 


High-level analysis of card spending. 


Number of cardholders, or Nucleus Clients with cards. 


Number of Nucleus Cards. 


Total amount spent over the analysis period. 


Number of card transactions, or Nucleus Portfolio Transactions linked 
to a card. 


Average card transaction amount over the analysis period. 


Historical total card spending data, with frequency dependent on the 
history frequency interval value passed in the request. Each 
entry has the fields shown below. 


Period start date. 


Period end date. 


Amount spent in the period. 


Cardholders that spent the most over the analysis period. Each entry 
represents a single cardholder and has the fields shown below. 


Name of the cardholder associated with the spending. 


Number of cards held by the cardholder. 


Total amount spent over the analysis period. 


Number of card transactions. 
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Field 


mean transaction amount 


history 


period start 


period end 


amount spent 


top cards 


card holder name 


institution name 


card name 


total amount spent 


number of transactions 


mean transaction amount 


history 


period start 


period end 


amount spent 


NUCLEUS DATA DEPENDENCIES 


e Client 
e Business 
e Card 
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Description 


Average card transaction amount over the analysis period. 


Historical cardholder spending data, with frequency dependent on the 
history frequency interval value passed in the request. Each 
entry has the fields shown below. 


Period start date. 


Period end date. 


Amount spent in the period. 


Cards that spent the most over the analysis period. Each entry 
represents a single card and has the fields shown below. 


Name of the cardholder that appears on the card. 


Name of the institution that issued the card. 


Name of the card associated with the spending. 


Total amount spent over the analysis period. 


Number of card transactions. 


Average card transaction amount over the analysis period. 


Historical card spending data, with frequency dependent on the 
history frequency interval value passed in the request. Each 
entry has the fields shown below. 


Period start date. 


Period end date. 


Amount spent in the period. 
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Account 

e Portfolio 


e Portfolio Transaction 
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Card Authorization 


Card Authorization provides the ability to authorize a card transaction based on a variety of pre-defined 
spending controls. For spending control authorizations, information about the transaction, such as transaction 
type, transaction category, merchant, and location is consumed by the service. This information, along with the 
client’s card transaction history, is compared to existing spending and transaction limits. If the limits have not 
been or will not be exceeded by the transaction, it will be authorized. Cleansing of raw transaction data, 
utilization of audit logs, and full and partial authorizations of the requested amount are supported. 


HTTP REQUEST 


POST /card_authorization 


Example Request 


curl -X POST -H "Authorization: Bearer <access_token>" \ 

-H "Content-Type: application/json" ^ 

«d 27 
"card id": "3f2a4530-a0f5-4eca-a7b1-c151b1175f99", 
"currency code": "USD", 
"auth type": | 

"spending control" 

L 
"amount": 300, 
"date": "2020-11-20T08:00:00.000+0000", 
"transaction type": "purchase", 
"merchant id": "87ef9136-f7e1-4ef0-8dbc-e58bf435d11c", 
"merchant": "Delta", 
"merchant category code": 2345, 
"mid": "123456790", 
"transaction category id": "48f67eea-0ae6-4396-add7-65f57c515367", 


"transaction category": "Travel", 
"description": "DELTA AIRLINES #235920", 
"memo": null, 


"location": { 
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"country": "US" 


z E 
= "partial_auth": false, 
"cleanse_data": false, 
"use audit log": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/card authorization" 
ARGUMENTS 
Parameter Description 
card id The ID of a Nucleus Card that the transaction corresponds to. 


UUID, required 


currency code The alphabetic currency code of the transaction, limited to 3 characters. 
string, required Only records with this currency code will be considered. See Currencies. 
auth type The type of authorization to be performed on the transaction. Value may 
array[string], required be spending control. H spending control is passed, the transaction 


will be authorized if it does not exceed any of the existing Nucleus 
Spending Controls. 


amount Amount of the transaction to be authorized. A negative value indicates a 
float, required debit, while a positive value indicates a credit. 
date Date and time of the transaction to be authorized. 


timestamp, required 


transaction type Type of the transaction to be authorized. Value may be purchase, 

string, required atm withdrawal, or other. 

transaction category Name of the category of the transaction to be authorized. See Transaction 
string Categories. 


transaction category id ID ofthe category of the transaction to be authorized. See Transaction 


UUID Categories. 

merchant Name of the merchant of the transaction to be authorized. See Merchants. 
string 

merchant id ID of the merchant of the transaction to be authorized. See Merchants. 
UUID 
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Parameter 


mid 


string 


merchant_category_code 


string 


description 


string 


memo 


string 


location 


object 


country 


string 


partial auth 
boolean 


cleanse data 


boolean 


use audit log 


boolean 


Example Response 


Hydrogen Proton API Reference 


Description 


Internal merchant ID of the transaction to be authorized. 


Merchant category code of the transaction to be authorized. 


Description of the transaction to be authorized. 


Memo of the transaction to be authorized. 


Location details of the transaction to be authorized. 


ISO 3166 ALPHA-2 country code of the transaction to be authorized. See 
Countries. 


If true, a portion of the transaction amount may be authorized. Defaults 
to false, meaning only the full transaction amount may be authorized. 


If true, some of the transaction data provided in this request will be 
submitted for data cleansing prior to any analysis. This data may include 
merchant, merchant category code, description, memo, and 
amount . Defaults to false, meaning that no additional data cleansing 
will be performed on the transaction data provided. This service requires 
access to the plasma premium offering. 


If true, the most recent Audit Log created by Card Limit Check will be 
utilized to derive the current status of any spending controls. Defaults to 
false, meaning that the status of any spending controls will be derived 
dynamically in this analysis. 


"is authorized": true, 


"requested amount": 1300.0, 


"authorized amount": 1000.0, 


19/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


"rejected amount": 300.0, 
"rejection details": { 


NAV Ill 


"message": "atm withdrawal spending limit", 

"spending control id": "5d6e3328-09f4-4450-bb56-2ab9751fc0d7", 
"control type": "spending limit", 

"control scope": "atm withdrawal", 

"control value": null, 

"frequency unit": "one time", 

"frequency": 1, 

"limit value": 1000.0, 

"limit used": 0, 

"limit remaining": 1000.0 


} 
} 
RESPONSE 

Field Description 

is_authorized Indicates whether the transaction was successfully authorized. A value of true 
indicates that the transaction was fully or partially authorized, while a value of 
false indicates that the transaction was rejected. 

requested amount Amount requested to be authorized. 

authorized amount Amount authorized. 

rejected amount Amount rejected. 

rejection details Details of the rejection when all or a portion of the requested amount is rejected. 

message Message explaining the reason for the rejection. Value will be one of the following: 


all spending limit, purchase spending limit, 

atm withdrawal spending limit,transaction category spending limit 
transaction category id spending limit, merchant spending limit, 
merchant id spending limit, location spending limit, 

all transaction limit, purchase transaction limit, 

atm withdrawal transaction limit, 
transaction category transaction limit, 
transaction category id transaction limit, 

merchant transaction limit, merchant id transaction limit, 
location transaction limit, transaction category allow list, 
transaction category id allow list, merchant allow list, 
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spending control_id 


control_type 


control_scope 


control_value 


frequency unit 


frequency 


limit value 


limit used 


limit remaining 


existing balance 


new balance 


Hydrogen Proton API Reference 


Description 


merchant id allow list, location allow list, 
transaction category deny list, transaction category id deny list, 
merchant deny list, merchant id deny list, location deny list, 


mid restriction,time delay restriction. 
ID of the Nucleus Spending Control that triggered the rejection. 


Type of the spending control. Value may be spending limit, 
transaction limit, allow list,or deny list. 


Scope of the spending control. Value may be all, purchase, atm withdrawal 
or merchant category. 


Specific value that triggered the rejection. Will be one of the control values 
from the corresponding spending control. 


Frequency unit of the spending control. Value may be one time, daily, 
weekly, monthly, quarterly, or annually. 


Frequency of the spending control. Indicates the number of frequency unit 
between each period. 


Value of the spending control limit. 


Value already used towards this spending control limit. 


Value that remains to be used towards this spending control limit. 


Card balance prior to the processing of any newly authorized transaction. 


Card balance after the processing of any newly authorized transaction. 


NUCLEUS DATA DEPENDENCIES 


e Client 

e Account 

e Portfolio 

e Portfolio Asset Size 
e Portfolio Transaction 
e Transaction Code 

e Card 

e Spending Control 
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Card Limit Check makes it easy to monitor usage of a client’s cards relative to their set limits. This service 
analyzes a client’s spending and transaction limits against their card transaction history for the specified 
period. A detailed status of each individual limit is returned, indicating how much of the limit has been used or 
is remaining, whether or not the limit has been breached, and how much time is left in the period before the 
limit resets. 


HTTP REQUEST 


POST /card_limit_check 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"client id": "159bb162-b911-4c97-ba96-53493e62674d", 
"currency code": "USD", 
"as of date": "2020-12-15T00:00:00.00040000" , 
"create log": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/card limit check" 


ARGUMENTS 
Parameter Description 
client id The ID of a Nucleus Client for whom to conduct the analysis. 


UUID, required 


currency code The alphabetic currency code used to conduct the analysis, limited to 3 characters. 


string, required Only records with this currency code will be considered. See Currencies. 

as of date The date and time as of which to conduct the analysis. Defaults to the current date and 
datetime time. 

create log If true , a record of this Proton request URL, request body, response body, and 
boolean Nucleus UUID(s), where applicable, will be stored in Nucleus as an Audit Log, and the 


resulting audit log id will be returned in the Proton response. Audit logs created 
here can be utilized by the Card Authorization service. Defaults to false. 
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Example Response 


"as of date": "2020-12-15T00:00:00.000:0000", 
"currency code": "USD", 


"summary": 1 


"number of limits": 6, 


"number of limits breached": 1, 


"number of limits unbreached": 5 


D 


"limit check": [ 


{ 


"spending control id": "45e1a978-bf92-43b9-a26f-998738622003", 
"control type": "transaction limit", 

"control scope": "purchase", 

"control values": [], 

"frequency unit": "daily", 

"frequency": 1, 

"limit value": 1, 

"limit used": 1, 

"limit remaining": 0, 

"limit breached": true, 

"limit start date": "2020-12-15T00:00:00.00000040000", 
"limit reset date": "2020-12-16T00:00:00.00000040000" , 
"days until limit reset": 1, 

"is primary transaction category": [], 

"primary transaction category name": [] 


"spending control id": "b34c9e4a-66fe-4840-b73a-7b5f3a9dd552", 
"control type": "spending limit", 

"control scope": "purchase", 

"control values": [], 

"frequency unit": "annually", 

"frequency": 1, 

"limit value": 15000.0, 

"limit used": 2595.4, 

"limit remaining": 12404.6, 

"limit breached": false, 

"limit start date": "2020-01-01T00:00:00.000000«0000", 
"limit reset date": "2021-01-01T00:00:00.00000040000" , 
"days until limit reset": 17, 

"is primary transaction category": [], 

"primary transaction category name": [] 
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"spending control id": "591627da-f3d2-4ee0-bb6b-7838dbee3c36", 
"control type": "spending limit", 
"control scope": "atm withdrawal", 
"control values": [], 

"frequency unit": "one time", 
"frequency": 1, 

"limit value": 2000.0, 

"limit used": 0, 

"limit remaining": 2000.0, 

"limit breached": false, 

"limit start date": null, 

"limit reset date": null, 

"days until limit reset": null, 

"is primary transaction category": [], 
"primary transaction category name": [] 


"spending control id": "60d45207-b17a-4965-bd01-690ffbea0578", 


"control type": "spending limit", 
"control scope": "transaction category", 
"control values": [ 

"Pets" 
Ip 
"frequency unit": "monthly", 


"frequency": 1, 

"limit value": 1000.0, 

"limit used": 253.34, 

"limit remaining": 746.66, 

"limit breached": false, 

"limit start date": "2020-12-01T00:00:00.00000040000" , 
"limit reset date": "2021-01-01T00:00:00.00000040000", 
"days until limit reset": 17, 

"is primary transaction category": [], 

"primary transaction category name": [] 


"spending control id": "60d45207-b17a-4965-bd01-690ffbea0578", 
"control type": "spending limit", 
"control scope": "transaction category", 
"control values": [ 
"Personal Care" 
L 
"frequency unit": "monthly", 
"frequency": 1, 
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"limit used": 47.89, 

"limit remaining": 952.11, 
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"limit breached": false, 

"limit start date": "2020-12-01T00:00:00.00000040000", 
"limit reset date": "2021-01-01T00:00:00.00000040000" , 
"days until limit reset": 17, 

"is primary transaction category": [], 

"primary transaction category name": [] 


"spending control id": "60d45207-b17a-4965-bd01-690ffbea0578", 
"control type": "spending limit", 
"control scope": "transaction category", 
"control values": [ 
"Home" 
L 
"frequency unit": "monthly", 
"frequency": 1, 
"limit value": 1000.0, 
"limit used": 931.62, 
"limit remaining": 68.38, 
"limit breached": false, 
"limit start date": "2020-12-01T00:00:00.00000040000" , 
"limit reset date": "2021-01-01T00:00:00.00000040000", 
"days until limit reset": 17, 
"is primary transaction category": [], 
"primary transaction category name": [] 


RESPONSE 


Field Description 


as of date Date and time as of which the analysis is conducted. If 
as of date was provided in the request, it is reflected 
here. If as of date was not provided, this value is 
derived dynamically. 


currency code Currency code associated with monetary response 
values. 
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summary 


number_of_limits 


number of limits breached 


number of limits unbreached 


limit check 


spending control id 


control type 


control scope 


control values 


frequency unit 


frequency 


limit value 


limit used 


limit remaining 


limit breached 
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Description 


Summary of spending and transaction limits for the client. 


Total number of limits. 


Number of limits that have been breached. 


Number of limits that have not been breached. 


Detailed analysis of each spending and transaction limit. 


ID of the Nucleus Spending Control. 


Type of the spending control. Value may be 


spending limit or transaction_limit. 


Scope of the spending control. Value may be all, 
purchase, atm withdrawal, 
transaction category, transaction category id, 


merchant, merchant id,or location. 
Value of the spending control. Will be one of the 
control values from the corresponding spending 


control. 


Frequency unit of the spending control. Value may be 
one time, daily, weekly, monthly, quarterly, or 


annually. 


Frequency of the spending control. Indicates the number 
of frequency unit between each period. 


Value of the spending control limit. 


Value already used towards this spending control limit. 


Value that remains to be used towards this spending 
control limit. 


Indicates if the limit has been breached. Value of true 
indicates that the limit has been breached, while false 
indicates that the limit has not been breached. 
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Field 


limit_start_date 


limit_reset_date 


days_until_limit_reset 


is primary transaction category 


primary transaction category name 


audit log id 


NUCLEUS DATA DEPENDENCIES 


Client 

Account 

Portfolio 

Portfolio Asset Size 
Portfolio Transaction 
Transaction Code 

Card 

Spending Control 
Merchants 


Transaction Categories 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


Hydrogen Proton API Reference 


Description 


Start date of the control period determined by 
as of date. 


End date of the control period determined by 


as of date. 


Days remaining in the control period, calculated as the 
difference between the as of date and the 
limit reset date. 


If the spending control has control scope - 
transaction category id, indicates whether the 
control value is a primary 

transaction category id.A value of true indicates 
that itis a primary transaction category id. See 
Transaction Categories. 


If the spending control has control scope - 
transaction category id and control value isa 
primary transaction category id, then this will be the 
name of the category. See Transaction Categories. 


The ID of the Audit Log record created in Nucleus. Only 
returned when create log - true. 
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Business Financial Management 


Cash Analysis 


Cash Analysis offers detailed analytics on a business’s cash activity across all business accounts. It supports 
a full view of cash inflows and outflows over a given time period, as well as advanced cash burn metrics (both 
gross and net). The analysis combines transaction data with balance data to provide insight into where cash 
is, where it comes from, where it goes, and how each element of cash activity is trending over time. 


HTTP REQUEST 


POST /business/cash_analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" ^ 


-d '{ 
"client id": "dde2a06e-5069-4503-9fa6-19f7f5648a6a", 
"scope": "all", 

"currency code": "USD", 


"start date": "2019-08-15", 
"end date": "2020-08-15", 
"history frequency interval": "quarter", 
"show history": true, 
"show inflow details": true, 
"show outflow details": true, 
"only cleansed": true 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/business/cash analysis 


ARGUMENTS 
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client_id 
UUID 


scope 


string 


transaction status scope 


array[string] 


currency_code 


string 


currency_conversion 


string 


start_date 
date 


end_date 
date 


history frequency interval 
string 


Hydrogen Proton API Reference 


Description 


The ID of a Nucleus Client that represents the business to be 
analyzed. If not provided, the analysis will include data that is not 
linked to any client. 


The scope of data to be considered. Value must be one of the 
following: all, external, internal. Defaults to all, which will 
consider internal data, or Accounts, Portfolios, Portfolio Asset 
Sizes, and Portfolio Transactions, along with external data, or 
Aggregation Accounts, Aggregation Account Balances, and 
Aggregation Account Transactions. 


If populated, only transactions whose status matches one of the 
array values are considered in the analysis. Defaults to null, 
meaning all transactions are considered regardless of the status. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Only records with this currency code will be considered. 
Defaults to USD if currency conversion is not provided. If 
currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Records will be converted from their original currency to 
the one indicated here. Conversions are supported both to and from 
the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


The start date of the analysis period. Applies to both balance and 
transactional data. If there is no underlying data found, start date 
defaults to one day prior to end date. Else, start date defaults to 
the earliest date of available data. 


The end date of the analysis period. Applies to both balance and 
transactional data. Defaults to today's date. 


The frequency of historical cash balance and cash burn. Value can be 
one of day, week, month, quarter, or year. For cash balances, 
when set to a value other than day , a historical cash balance entry is 
returned for the end of each corresponding period. For example, with 
a value of month , the last day of each month in the analysis period 
will be reflected in the cash balance history. Cash burn history returns 
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= Parameter Description 

> 

= botha period_start and period_end date for each interval. 
Defaults to month . Only applicable when show history is true. 


show history Determines whether to return historical values for cash balance and 
boolean cash burn analysis. Defaults to false. 

show inflow details Determines whether to return details of all cash inflows. Defaults to 
boolean false. 

show outflow details Determines whether to return details of all cash outflows. Defaults to 
boolean false. 

only cleansed If true, only Portfolio Transactions with the is cleansed parameter 
boolean setto true will be considered. Defaults to false. 


Example Response 


"currency code": "USD", 
"analysis start": "2019-08-15", 
"analysis end": "2020-08-15", 
"cash balance": { 
"current balance": { 
"value": 41517.85, 
"date": "2020-08-15" 
bo 
"mean balance": 19858.66, 
"median balance": 20350.0, 
"min balance": { 
"value": 17950.0, 
"date": "2020-02-04" 
bo 
"max balance": { 
"value": 41517.85, 
"date": "2020-08-15" 
bo 
"change": { 
"1 day": { 
"value": 125.0, 
"percentage": 0.003 


D 
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"7 day": { 


"value": 18917.85, 
"percentage": 0.8371 


bo 
"30 day": { 
"value": 19142.85, 
"percentage": 0.8555 
Lë 
"60 day": { 
"value": 20017.85, 
"percentage": 0.9311 
bo 
"90 day": { 
"value": 20292.85, 
"percentage": 0.9561 
bo 
"180 day": { 
"value": 21167.85, 
"percentage": 1.0402 
bo 
"365 day": { 
"value": 23567.85, 
"percentage": 1.313 
ig 
"total": ( 
"value": 23567.85, 
"percentage": 1.313 
} 
J 
"history": [ 
{ 
"date": "2019-12-31", 
"balance": 17950.0, 
"balance change": { 
"value": null, 
"percentage": null 
} 
J 
{ 
"date": "2020-08-15", 
"balance": 41517.85, 
"balance change": { 
"value": 23567.85, 
"percentage": 1.313 
} 
} 
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d 
d 


"current burn": { 


ho 


"1 day": { 
"value": 254.24, 
"start": "2020-08-15", 
"end": "2020-08-15" 


bo 

"7 day": { 
"value": 405.08, 
"start": "2020-08-09", 
"end": "2020-08-15" 

bo 

"30 day": { 
"value": 1122.28, 
"start": "2020-07-17", 
"end": "2020-08-15" 

bo 

"60 day": { 
"value": 1724.69, 
"start": "2020-06-17", 
"end": "2020-08-15" 

bo 

"90 day": { 
"value": 2117.26, 
"start": "2020-05-18", 
"end": "2020-08-15" 

bo 

"180 day": { 
"value": 2266.09, 
"start": "2020-02-18", 
"end": "2020-08-15" 

bo 

"365 day": { 
"value": 4766.09, 
"start": "2019-08-17", 
"end": "2020-08-15" 

} 


"mean burn": { 


"1 day": 12.99, 
"7 day": 87.77, 
"30 day": 377.14, 
"60 day": 746.36, 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


32/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


= "90 day": 1128.29, 
a "180 day": 2372.58, 
z "365 day": 4596.6 
bo 
"median burn": { 
"1 day": 0.0, 
"7 day": 0.0, 
"30 day": 0.0, 
"60 day": 148.83, 
"90 day": 970.56, 
"180 day": 2500.0, 
"365 day": 4511.85 
bo 
"min burn": { 


"1 day": { 
"value": 0.0, 
"start": "2020-08-14", 
"end": "2020-08-14" 


bo 

"7 day": { 
"value": 0.0, 
"start": "2020-08-03", 
"end": "2020-08-09" 

bo 

"30 day": { 
"value": 0.0, 
"start": "2020-05-07", 
"end": "2020-06-05" 

bo 

"60 day": { 
"value": 0.0, 
"start": "2020-03-03", 
"end": "2020-05-01" 

bo 

"90 day": { 
"value": 9.9, 
"start": "2020-02-02", 
"end": "2020-05-01" 

bo 

"189 day": { 
"value": 970.56, 
"start": "2020-01-14", 
"end": "2020-07-11" 

bo 

"365 day": { 


"value": 4511.85, 
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"start": "2019-08-16", 
"end": "2020-08-14" 


} 
bo 
"max burn": { 
"1 day": { 
"value": 2500.0, 
"start": "2020-01-03", 
"end": "2020-01-03" 
bo 
"7 day": { 
"value": 2500.0, 
"start": "2020-01-03", 
"end": "2020-01-09" 
bo 
"30 day": { 
"value": 2500.0, 
"start": "2020-01-03", 
"end": "2020-02-01" 
bo 
"60 day": { 
"value": 2500.0, 
"start": "2020-01-03", 
"end": "2020-03-02" 
bo 
"90 day": { 
"value": 2500.0, 
"start": "2020-01-03", 
"end": "2020-04-01" 
bo 
"180 day": { 
"value": 3470.56, 
"start": "2020-01-03", 
"end": "2020-06-30" 
bo 
"365 day": { 
"value": 4766.09, 
"start": "2019-08-17", 
"end": "2020-08-15" 
} 
} 
bo 
"net": { 
"current burn": { 
"1 day": { 


"value": -125.0, 
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"start": "2020-08-15", 
"end": "2020-08-15" 


bo 

"7 day": { 
"value": -18917.85, 
"start": "2020-08-09", 
"end": "2020-08-15" 

bo 

"30 day": { 
"value": -19142.85, 
"start": "2020-07-17", 
"end": "2020-08-15" 

bo 

"60 day": { 
"value": -20017.85, 
"start": "2020-06-17", 
"end": "2020-08-15" 

bo 

"90 day": { 
"value": -20292.85, 
"start": "2020-05-18", 
"end": "2020-08-15" 

bo 

"180 day": { 
"value": -21167.85, 
"start": "2020-02-18", 
"end": "2020-08-15" 

bo 

"365 day": { 
"value": -23567.85, 
"start": "2019-08-17", 
"end": "2020-08-15" 

Jj 


"mean burn": { 


bo 


"1 day": -64.22, 

"7 day": -253.82, 
"30 day": -574.2, 
"60 day": -1003.91, 
"90 day": -1472.58, 
"180 day": -3504.14, 
"365 day": -23501.18 


"median burn": { 


"1 day": 0. 
"7 day": 0. 


© © 
` v 
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"30 day": 0.0, 

"60 day": -725.0, 
"90 day": -1000.0, 
"180 day": -3275.0, 
"365 day": -23492.85 


"min burn": { 


D 


"1 day": { 
"value": -17692.85, 
"start": "2020-08-13", 
"end": "2020-08-13" 


bo 

"7 day": { 
"value": -18917.85, 
"start": "2020-08-09", 
"end": "2020-08-15" 

bo 

"30 day": { 
"value": -19142.85, 
"start": "2020-07-17", 
"end": "2020-08-15" 

bo 

"60 day": { 
"value": -20017.85, 
"start": "2020-06-17", 
"end": "2020-08-15" 

ho 

"90 day": { 
"value": -20292.85, 
"start": "2020-05-18", 
"end": "2020-08-15" 

bo 

"189 day": { 
"value": -21167.85, 
"start": "2020-02-18", 
"end": "2020-08-15" 

bo 

"365 day": { 
"value": -23567.85, 
"start": "2019-08-17", 
"end": "2020-08-15" 

} 


"max burn": ( 


"1 day": { 
"value": 850.0, 
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"start": "2020-05-10", 
"end": "2020-05-10" 


bo 

"7 day": { 
"value": 850.0, 
"start": "2020-05-10", 
"end": "2020-05-16" 

bo 

"30 day": { 
"value": 850.0, 
"start": "2020-05-10", 
"end": "2020-06-08" 

bo 

"60 day": { 
"value": 575.0, 
"start": "2020-05-06", 
"end": "2020-07-04" 

bo 

"90 day": { 
"value": 0.0, 
"start": "2019-11-07", 
"end": "2020-02-04" 

bo 

"189 day": { 
"value": -2175.0, 
"start": "2020-02-08", 
"end": "2020-08-05" 

bo 

"365 day": { 
"value": -23442.85, 
"start": "2019-08-16", 
"end": "2020-08-14" 

} 

D 
"history": [ 


( 


"period start": "2019-08-15", 
"period end": "2019-12-31", 


"gross burn": 0.0, 
"gross burn change": ( 
"value": null, 

"percentage": null 
J 
"net burn": 0.0, 
"net burn change": { 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


37/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


"value": null, 
"percentage": null 


NAV Ill 


“period start": "2020-01-01", 

"period end": "2020-08-15", 

"gross burn": 4766.09, 

"gross burn change": { 
"value": 4766.09, 
"percentage": null 

Jo 

"net_burn": -23567.85, 

"net burn change": { 
"value": -23567.85, 
"percentage": null 


bo 
"inflow details": { 


"by category": [ 


{ 
"category": "Income", 
"value": 5016.34, 
"subcategories": [ 
{ 
"subcategory": "Deposits", 
"value": 5000.0 
bo 
{ 
"subcategory": "Refunds", 
"value": 16.34 
} 
] 
} 
L 
"by merchant": [ 
{ 
"merchant": "Paypal", 
"value": 5000.0 
bo 
{ 
"merchant": null, 
"value": 16.34 
} 
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]; 


"outliers": [] 


NAV Ill 


bo 
"outflow details": { 
"by category": [ 


{ 
"category": "Professional Services", 
"value": 4766.09, 
"subcategories": [ 
{ 
"subcategory": "Consulting", 
"value": 2500.0 
bo 
{ 
"subcategory": "Security", 
"value": 472.92 
bo 
£ 
"subcategory": "Printing", 
"value": 1110.67 
bo 
{ 
"subcategory": "Marketing", 
"value": 682.5 
} 
] 
} 
L 
"by merchant": [ 
{ 
"merchant": "BCG", 
"value": 2500.0 
bo 
{ 
"merchant": "ADT Inc", 
"value": 472.92 
bo 
{ 
"merchant": "FedEx Office", 
"value": 1110.67 
bo 
{ 
"merchant": "ABC Advisors", 
"value": 682.5 
} 
L 
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"outliers": [ 


{ 


NAV Ill 


"id": "48919fbd-2586-4604-9f26-71552dcb82a5", 
"aggregation account id": "d1912596-8031-49a6-b89b-c350e8e3b362", 
"transaction date": "2020-01-03T00:00:00.00040000", 
"status": null, 
"bank credit": ( 
"transaction type": "Debit", 
"amount": 2500.0, 
"merchant": "BCG", 
"category": "Professional Services", 
"subcategory": "Consulting", 
"description": null, 
"memo": null, 
"location": {} 
bo 
"investment": {}, 
"cash": {}, 
"currency code": "USD", 
"is excluded analysis": false, 
"is fee": false, 
"is transfer": null, 
"is recurring": false, 
"metadata": {}, 
"secondary id": null, 
"create date": "2020-08-19T19:43:36.61840000", 
"update date": "2020-08-19T19:43:36.61840000" 


RESPONSE 


Field Description 


currency code Currency code associated with monetary response values. 


analysis start Start date of the analysis period. If start date was provided in the request, 
itis reflected here. If start date was not provided, this value is derived 
dynamically. 


analysis end End date of the analysis period. If end date was provided in the request, 
itis reflected here. If end date was not provided, this value is derived 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 40/440 


8/3/23, 5:08 PM 


Field 


NAV Ill 


cash_balance 


current_balance 


value 


date 


mean_balance 


median_balance 


min_balance 


value 


date 


max_balance 


value 


date 


change 


1_day 


value 


percentage 


7_day 


value 


percentage 


30 day 


Hydrogen Proton API Reference 


Description 


dynamically. 


Analytics on cash balance activity over time. 


Most recent cash balance, as of the end of the analysis period. 


Cash balance value. 


Effective date for cash balance. 


Mean daily cash balance over the analysis period. 


Median daily cash balance over the analysis period. 


Minimum daily cash balance over the analysis period. 


Cash balance value. 


Effective date for cash balance. 


Maximum daily cash balance over the analysis period. 


Cash balance value. 


Effective date for cash balance. 


Cash balance change metrics over various periods as of the analysis end 
date. Only the change periods that are encapsulated in the analysis 


period are returned. 


Change over the past 1 day. 


Absolute balance change. 


Percentage balance change. 


Change over the past 7 days. 


Absolute balance change. 


Percentage balance change. 


Change over the past 30 days. 
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= Field Description 

à 

= value Absolute balance change. 
percentage Percentage balance change. 

60 day Change over the past 60 days. 
value Absolute balance change. 
percentage Percentage balance change. 

90 day Change over the past 90 days. 
value Absolute balance change. 
percentage Percentage balance change. 

180 day Change over the past 180 days. 
value Absolute balance change. 
percentage Percentage balance change. 

365 day Change over the past 365 days. 
value Absolute balance change. 
percentage Percentage balance change. 

total Change over the full analysis period. 
value Absolute balance change. 
percentage Percentage balance change. 

history Historical balance data, with frequency dependent on the 


history frequency interval value passed in the request. Each entry 
has the fields shown below. 


date Effective date for cash balance. 
balance Cash balance value. 
balance change Change in balance from the prior period. 
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Field 
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value 


percentage 


cash_burn 


gross 


current_burn 


1_day 


value 


start 


end 


7_day 


value 


start 


end 


30 day 


value 


start 


end 


60 day 


value 


start 


Hydrogen Proton API Reference 


Description 


Absolute balance change. 


Percentage balance change. 


Analytics on cash burn over time. Positive burn values indicate decreases 
in cash, while negative burn values indicate increases in cash. 


Gross cash burn metrics. Gross reflects cash outflow activity, regardless 
of inflows. Only the burn periods that are encapsulated in the analysis 
period are returned. 


Most recent gross burn, as of the end of the analysis period. 


Current 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 7-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 60-day cash burn. 


Cash burn value. 


Cash burn start date. 
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= Field 
3 

end 

90 day 
Value 
start 
end 

180 day 
Value 
start 
end 

365 day 
Value 
start 
end 

mean burn 

1 day 

7 day 

30 day 

60 day 

90 day 

180 day 

365 day 


median burn 


Hydrogen Proton API Reference 


Description 


Cash burn end date. 


Current 90-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 180-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 365-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Mean gross cash burn over various periods. 


Mean 1-day cash burn. 


Mean 7-day cash burn. 


Mean 30-day cash burn. 


Mean 60-day cash burn 


Mean 90-day cash burn. 


Mean 180-day cash burn. 


Mean 365-day cash burn. 


Median gross cash burn over various periods. 
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= Field 
à 
= 1_day 
7_day 
30 day 
60 day 
90 day 
180 day 
365 day 
min burn 
1 day 
value 
start 
end 
7 day 
value 
start 
end 
30 day 
value 
start 
end 
60 day 
value 


Hydrogen Proton API Reference 


Description 


Median 1-day cash burn. 


Median 7-day cash burn. 


Median 30-day cash burn. 


Median 60-day cash burn. 


Median 90-day cash burn. 


Median 180-day cash burn. 


Median 365-day cash burn. 


Minimum gross cash burn over various periods. 


Minimum 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 7-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 60-day cash burn. 


Cash burn value. 
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Field 


NAV Ill 


start 


end 


90 day 


value 


start 


end 


180 day 


value 


start 


end 


365_day 


value 


start 


end 


max_burn 


1_day 


value 


start 


end 


7_day 


value 


start 


Hydrogen Proton API Reference 


Description 


Cash burn start date. 


Cash burn end date. 


Minimum 90-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 180-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 365-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum gross cash burn over various periods. 


Maximum 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 7-day cash burn. 


Cash burn value. 


Cash burn start date. 
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end 


30 day 


value 


start 


end 


60 day 


value 


start 


end 


90 day 


value 


start 


end 


180 day 


value 


start 


end 


365 day 


value 


start 


end 


net 


Hydrogen Proton API Reference 


Description 


Cash burn end date. 


Maximum 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 60-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 90-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 180-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 365-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Net cash burn metrics. Net reflects both inflow and outflow cash activity. 
Only the burn periods that are encapsulated in the analysis period are 
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Field 
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current_burn 


1_day 


value 


start 


end 


7_day 


value 


start 


end 


30 day 


value 


start 


end 


60 day 


value 


start 


end 


90 day 


value 


start 


end 


Hydrogen Proton API Reference 


Description 


returned. 


Most recent net burn, as of the end of the analysis period. 


Current 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 7-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 60-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 90-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 
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à 
= 180 day 
value 
start 
end 
365_day 
value 
start 
end 
mean_burn 
1_day 
7_day 
30 day 
60 day 
90 day 
180 day 
365 day 


median burn 


1 day 


7 day 


30 day 


60 day 


90 day 


Hydrogen Proton API Reference 


Description 


Current 180-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Current 365-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Mean net cash burn over various periods. 


Mean 1-day cash burn. 


Mean 7-day cash burn. 


Mean 30-day cash burn. 


Mean 60-day cash burn 


Mean 90-day cash burn. 


Mean 180-day cash burn. 


Mean 365-day cash burn. 


Median net cash burn over various periods. 


Median 1-day cash burn. 


Median 7-day cash burn. 


Median 30-day cash burn. 


Median 60-day cash burn. 


Median 90-day cash burn. 
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Field 
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180 day 


365_day 


min_burn 


1_day 


value 


start 


end 


7_day 


value 


start 


end 


30 day 


value 


start 


end 


60 day 


value 


start 


end 


90 day 


value 


start 


Hydrogen Proton API Reference 


Description 


Median 180-day cash burn. 


Median 365-day cash burn. 


Minimum net cash burn over various periods. 


Minimum 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 7-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 60-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 90-day cash burn. 


Cash burn value. 


Cash burn start date. 
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Field 
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end 


180 day 


value 


start 


end 


365_day 


value 


start 


end 


max_burn 


1_day 


value 


start 


end 


7_day 


value 


start 


end 


30 day 


value 


start 


end 


Hydrogen Proton API Reference 


Description 


Cash burn end date. 


Minimum 180-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Minimum 365-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum net cash burn over various periods. 


Maximum 1-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 7-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 


Maximum 30-day cash burn. 


Cash burn value. 


Cash burn start date. 


Cash burn end date. 
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= Field Description 
à 
zZ 60 day Maximum 60-day cash burn. 
value Cash burn value. 
start Cash burn start date. 
end Cash burn end date. 
90 day Maximum 90-day cash burn. 
value Cash burn value. 
start Cash burn start date. 
end Cash burn end date. 
180 day Maximum 180-day cash burn. 
value Cash burn value. 
start Cash burn start date. 
end Cash burn end date. 
365 day Maximum 365-day cash burn. 
value Cash burn value. 
start Cash burn start date. 
end Cash burn end date. 
history Historical cash burn data with frequency dependent on the 


history frequency interval value passed in the request. Each entry 
has the fields shown below. 


period start Period start date. 
period end Period end date. 
gross burn Gross cash burn in the period. 


gross burn change Change in gross cash burn from the prior period. 
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Field 


value 


percentage 


net_burn 


net_burn_change 


value 


percentage 


inflow_details 


by_category 


category 


value 


subcategories 


subcategory 


value 


by_merchant 


merchant 


value 


outliers 


outflow_details 


by_category 


Hydrogen Proton API Reference 


Description 


Absolute gross cash burn change. 


Percentage gross cash burn change. 


Net cash burn in the period. 


Change in net cash burn from the prior period. 


Absolute net cash burn change. 


Percentage net cash burn change. 


Advanced analytics on cash inflows over the analysis period. 


List of cash inflows separated by categories and their relative 
subcategories. 


Category as defined in the Nucleus transactions. 

Sum of all transactions over the period for the given category. 

List of cash inflow subcategories as defined in the Nucleus transactions. 
Subcategory as defined in the Nucleus transactions. 

Sum of all transactions over the period for the given subcategory. 

List of cash inflows separated by merchant. 

Merchant as defined in the Nucleus transactions. 

Sum of all transactions over the period for the given merchant. 

List of inflow transactions whose amount is beyond 2.5 median absolute 
deviations from the median of all transaction amounts. Each entry 
represent a raw transaction record from Nucleus. Please see Nucleus 


Portfolio Transaction and Aggregation Account Transaction for more 
details on underlying fields. 


Advanced analytics on cash outflows over the analysis period. 


List of cash outflows separated by categories and their relative 
subcategories. 
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Field 


category 


value 


subcategories 


subcategory 


value 


by_merchant 


merchant 


value 


outliers 


NUCLEUS DATA DEPENDENCIES 


Client 

Account 

Portfolio 

Portfolio Asset Size 
Portfolio Transaction 


Aggregation Account 


Hydrogen Proton API Reference 


Description 


Category as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given category. 


List of cash outflow subcategories as defined in the Nucleus transactions. 


Subcategory as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given subcategory. 


List of cash outflows separated by merchant. 


Merchant as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given merchant. 


List of outflow transactions whose amount is beyond 2.5 median absolute 
deviations from the median of all transaction amounts. Each entry 
represent a raw transaction record from Nucleus. Please see Nucleus 
Portfolio Transaction and Aggregation Account Transaction for more 
details on underlying fields. 


Aggregation Account Balance 


Aggregation Account Transaction 


Customer Analysis 


Customer Analysis looks at a business’s customers in a revenue context to help frame customer activity in a 


meaningful way. It offers summary-level revenue metrics, advanced stats on individual payments, a view of the 
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HTTP REQUEST 


Hydrogen Proton API Reference 


firm’s top customers, and benchmarked trend indicators. Use this service to keep track of customer revenue 
over time and to assess the revenue health of a business. 


POST /business/customer_analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" ^ 


e ae 


"client id": "9e0dd1c0-7669-47ff-9a32-b10434df36dd", 
"currency code": "USD", 

"start date": "2020-07-01", 

"end date": "2020-07-31", 

"benchmark start date": "2020-06-01", 
"benchmark end date": "2020-06-30", 

"response limit": 3, 


"only active customers": false 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/business/customer anal 


ARGUMENTS 


Parameter 


client id 
UUID 


business id 
UUID 


customer ids 
array[UUID] 


Description 


The ID of a Nucleus Client that represents the business to be analyzed. Must 
have client type of firm. If provided, all customers linked to this client 
will be analyzed. If one of client id, business id,or customer ids is 
not provided, the analysis will include data that is not linked to any client or 
business. 


The ID of a Nucleus Business that represents the business to be analyzed. If 
provided, all customers linked to this business will be analyzed. If one of 
client id, business id,or customer ids is not provided, the analysis 
will include data that is not linked to any client or business. 


The ID(s) of Nucleus Contact(s) to be analyzed. A contact is considered a 
customer if the is customer parameter is set to true. If one of 

client id, business id,or customer ids is not provided, the analysis 
will include data that is not linked to any client or business. 
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Parameter 


currency_code 


string 


currency_conversion 


string 


start_date 
date 


end_date 
date 


benchmark_start_date 
date 


benchmark_end_date 
date 


response limit 


integer 


only active customers 


boolean 


Example Response 


Hydrogen Proton API Reference 


Description 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Only records with this currency code will be considered. Defaults 
to USD if currency conversion is not provided. If 

currency conversion is provided, all origin currencies will be considered 
by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Records will be converted from their original currency to the one 
indicated here. Conversions are supported both to and from the following 
currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies. 


Start date of the analysis period. Default to the earliest date of available 
data. 


End date of the analysis period. Defaults to today's date. 


Start date of the benchmark analysis period. Default values for 
benchmark start date and benchmark end date are based on the 
difference between start date and end date. For example, if 

start date and end date are 2016-06-15 and 2016-06-17, 
respectively, benchmark start date and benchmark end date default 
to 2016-06-12 and 2016-06-14, respectively. 


End date of the benchmark analysis period. Default values for 

benchmark start date and benchmark end date are based on the 
difference between start date and end date. For example, if 

start date and end date are 2016-06-15 and 2016-06-17, 
respectively, benchmark start date and benchmark end date default 
to 2016-06-12 and 2016-06-14, respectively. 


Maximum number of records to be returned in top customers. 


If true , only include Nucleus Customers with is active setto true in 


this analysis. Defaults to false, so that both active and inactive customers 
are included. 
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"currency code": "USD", 
"base start date": "2020-07-01", 
"base end date": "2020-07-31", 
"benchmark start date": "2020-06-01", 
"benchmark end date": "2020-06-30", 
"summary": { 

"number of customers": { 


"base": 2, 

"benchmark": 3, 

"change": { 
"value": -1, 


"percentage": -0.3333 


bo 

"number of payments": { 
"base": 2, 
"benchmark": 4, 


"change": { 
"value": -2, 
"percentage": -0.5 
3 


bo 
"total customer revenue": { 
"base": 14500.0, 
"benchmark": 24600.0, 
"change": { 
"value": -10100.0, 
"percentage": -0.4106 


bo 
"payment details": { 
"mean payment": { 
"base": 7250.0, 
"benchmark": 6150.0, 
"change": { 
"value": 1100.0, 
"percentage": 0.1789 


J 

"median payment": { 
"base": 7250.0, 
"benchmark": 6800.0, 
"change": { 
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= "value": 450.0, 
a "percentage": 0.0662 
< } 
bo 
"min payment": { 
"base": { 
"company name": "Initech Printers", 
"date": "2020-07-15", 
"amount": 5750.0 
bo 
"benchmark": { 
"company name": "Cube Financial", 
"date": "2020-06-08", 
"amount": 1500.0 
bo 
"change": { 
"value": 4250.0, 
"percentage": 2.8333 
} 
bo 
"max payment": { 
"base": { 
"company name": "Gradient Entertainment", 
"date": "2020-07-10", 
"amount": 8750.0 
bo 
"benchmark": { 
"company name": "Gradient Entertainment", 
"date": "2020-06-02", 
"amount": 9500.0 
bo 
"change": { 
"value": -750.0, 
"percentage": -0.0789 
} 
3 
bo 
"top customers": [ 
{ 
"company name": "Gradient Entertainment", 
"number of payments": { 
"base": 1, 
"benchmark": 2, 
"change": { 
"value": -1, 


"percentage": -0.5 
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= } 
> }, 
= "total customer revenue": { 
"base": 8750.0, 
"benchmark": 16825.0, 
"change": { 
"value": -8075.0, 
"percentage": -0.4799 
} 
bo 
"receivable overdue": 2500.0, 
"receivable outstanding": 3000.0 
bo 
d 
"company name": "Initech Printers", 
"number of payments": { 
"base": 1, 
"benchmark": 1, 
"change": { 
"value": 0, 
"percentage": 0.0 
} 
bo 
"total customer revenue": { 
"base": 5750.0, 
"benchmark": 6275.0, 
"change": { 
"value": -525.0, 
"percentage": -0.0837 
} 
bo 
"receivable overdue": 7500.0, 
"receivable outstanding": 12500.0 
} 
] 
} 
RESPONSE 
Field Description 
currency_code Currency code associated with monetary response values. 
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Field 


NAV Ill 


base_start_date 


base end date 


benchmark start date 


benchmark end date 


summary 


number of customers 


base 


benchmark 


change 


value 


percentage 


number of payments 


base 


benchmark 


change 


Hydrogen Proton API Reference 


Description 


Start date of the analysis period. If start date was provided in the 
request, it is reflected here. If start date was not provided, this value 
is derived dynamically. 


End date of the benchmark period. If end date was provided in the 
request, it is reflected here. If end date was not provided, this value is 
derived dynamically. 


Start date of the benchmark period. If benchmark start date was 
provided in the request, it is reflected here. If benchmark start date 
was not provided, this value is derived dynamically. 


End date of the benchmark period. If benchmark end date was 
provided in the request, it is reflected here. If benchmark end date 
was not provided, this value is derived dynamically. 


High-level analysis of all customer revenue. 


Number of customers for which revenue was recorded. 


Number of customers for which revenue was recorded during the base 
analysis period. 


Number of customers for which revenue was recorded during the 
benchmark period. 


Difference in number of customers between the base and benchmark 
periods. 


Absolute difference in number of customers. 


Percentage difference in number of customers. 


Number of revenue payments made across all customers. 


Number of revenue payments made during the base analysis period. 


Number of revenue payments made during the benchmark analysis 
period. 


Difference in number of revenue payments between the base and 
benchmark periods. 
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= Field Description 

> 

q 

" value Absolute difference in number of revenue payments. 
percentage Percentage difference in number of revenue payments. 


total customer revenue Total revenue recorded across all customers. 


base Total revenue recorded during the base analysis period. 
benchmark Total revenue recorded during the benchmark period. 
change Difference in total revenue between the base and benchmark periods. 
value Absolute difference in total revenue. 
percentage Percentage difference in total revenue. 
payment details Customer revenue payment metrics. 
mean payment Arithmetic mean payment. 
base Mean payment during the base analysis period. 
benchmark Mean payment during the benchmark analysis period. 
change Difference in mean payment between the base and benchmark periods. 
value Absolute difference in mean payment. 
percentage Percentage difference in mean payment. 
median payment Median (e.g. 50th percentile) payment. 
base Median payment during the base analysis period. 
benchmark Median payment during the benchmark analysis period. 
change Difference in median payment between the base and benchmark 
periods. 
value Absolute difference in median payment. 
percentage Percentage difference in median payment. 
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= Field 
à 
= min_payment 
base 
company_name 
date 
amount 
benchmark 
company_name 
date 


amount 


change 


value 
percentage 
max_payment 
base 
company_name 
date 
amount 
benchmark 
company_name 
date 


amount 


Hydrogen Proton API Reference 


Description 


Minimum (e.g. smallest) payment. 


Minimum payment during the base analysis period. 


Company name associated with the payment. 


Date of the payment. 


Amount of the payment. 


Minimum payment during the benchmark period. 


Company name associated with the payment. 


Date of the payment. 


Amount of the payment. 


Difference in minimum payment between the base and benchmark 


periods. 


Absolute difference in minimum payment. 


Percentage difference in minimum payment. 


Maximum (e.g. largest) payment. 


Maximum payment during the base analysis period. 


Company name associated with the payment. 


Date of the payment. 


Amount of the payment. 


Maximum payment during the benchmark period. 


Company name associated with the payment. 


Date of the payment. 


Amount of the payment. 
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Field 


NAV Ill 


change 


value 


percentage 


top_customers 


company_name 


number_of_payments 


base 


benchmark 


change 


value 


percentage 


total_customer_revenue 


base 


benchmark 


change 


value 


percentage 


receivable overdue 


receivable outstanding 
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Description 


Difference in maximum payment between the base and benchmark 
periods. 


Absolute difference in maximum payment. 


Percentage difference in maximum payment. 


Customers who generated the most revenue over the base analysis 
period. Each entry represents a single customer and has the fields 
shown below. 


Company name of the customer. 


Number of revenue payments made by this customer. 


Number of revenue payments made during the base analysis period. 


Number of revenue payments made during the benchmark analysis 
period. 


Difference in number of revenue payments between the base and 
benchmark periods. 


Absolute difference in number of revenue payments. 


Percentage difference in number of revenue payments. 


Total revenue recorded for this customer. 


Total revenue recorded during the base analysis period. 


Total revenue recorded during the benchmark period. 


Difference in total revenue between the base and benchmark periods. 


Absolute difference in total revenue. 


Percentage difference in total revenue. 


Total receivables for this customer that are overdue. 


Total receivables for this customer that are outstanding. 
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NUCLEUS DATA DEPENDENCIES 


e Client 
e Contact 


NAV Ill 


e Customer Revenue 


Financial Health Check (Business) 


Financial Health Check evaluates the health of a business via a series of key financial ratios. It automatically 
calculates all available metrics and provides a pass/fail indicator that compares each metric to a rule-of-thumb 
benchmark. Benchmark values can be configured to further align with a specific business's industry, size, or 
other unique factors. This tool is designed to provide a high-level snapshot of business financial health. 


HTTP REQUEST 


POST /business/financial health check 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" ^ 
-d '( 
"ratio targets": { 
"profit margin": 0.1, 
"return on assets": 0.05, 
"return on equity": 0.15, 
"debt to equity": 1.5, 
"debt ratio": 0.5, 
"asset turnover": 1.0 
bo 
"client id": "e4a0dc1a-df02-4630-af44-1489f16598a5", 
"currency code": "USD", 
"accounting method": "accrual", 
"period type": "calendar", 
"period length": "quarterly" 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/business/financial heec 


ARGUMENTS 
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zi 
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Parameter 


ratio_targets 


map 


profit_margin 
float 


return_on_assets 
float 


return_on_equity 
float 


debt to equity 
float 


debt ratio 
float 


asset turnover 
float 


net income 
float 


total revenue 
float 


total assets 
float 


total liabilities 
float 


total equity 
float 


client id 
UUID 


Hydrogen Proton API Reference 


Description 


Benchmark values for each of the calculated metrics. Used to perform 
comparative analysis. 


Benchmark value for Profit Margin. Defaults to 0.1. 


Benchmark value for Return on Assets. Defaults to 0.05. 


Benchmark value for Return on Equity. Defaults to 0.15. 


Benchmark value for Debt-to-Equity ratio. Defaults to 1.5. 


Benchmark value for Debt Ratio. Defaults to 0.5. 


Benchmark value for Asset Turnover. Defaults to 1.0. 


Raw input for net income. If provided, takes precedent over data sourced from 


Nucleus. 


Raw input for total revenue. If provided, takes precedent over data sourced 
from Nucleus. 


Raw input for total assets. If provided, takes precedent over data sourced from 
Nucleus. 


Raw input for total liabilities. If provided, takes precedent over data sourced 
from Nucleus. 


Raw input for total shareholder's equity. If provided, takes precedent over data 
sourced from Nucleus. 


The ID of a Nucleus Client that represents the business to be analyzed. Must 
have client type of firm. If neithera client id, business id, or raw 
values are provided for each input, the analysis will include data that is not 
linked to any client or business. 
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Parameter 


business id 
UUID 


currency code 


string 


currency conversion 


string 


accounting method 


string 


period type 


string 


period length 


string 


period year 


integer 


period quarter 


integer 


period month 


integer 


Example Response 


"currency code" 
"profit margin" 


Hydrogen Proton API Reference 


Description 


The ID of a Nucleus Business that represents the business to be analyzed. If 
neither a client id, business id, or raw values are provided for each 


input, the analysis will include data that is not linked to any client or business. 


The alphabetic currency code used to conduct the analysis, limited to 3 


characters. Only records with this currency code will be considered. Defaults to 


USD if currency conversion is not provided. If currency conversion is 
provided, all origin currencies will be considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Records will be converted from their original currency to the one 
indicated here. Conversions are supported both to and from the following 
currency codes: USD, GBP, EUR, AUD, CAD, CHF. See Currencies. 


The financial statement accounting method to consider. Value may be 
accrual or cash. If not provided, Nucleus records with any period type will 
be considered. 


The income statement period type to consider. Value may be calendar or 
fiscal. If not provided, Nucleus records with any period type will be 
considered. 


The income statement period length to consider. Value may be annual, 
quarterly, monthly, ytd, qtd, or mtd. Defaults to quarterly. 


The income statement period length to consider. If not provided, defaults to the 


most recent available year found in an applicable financial statement. 


The income statement period quarter to consider. If not provided, defaults to 
the most recent available quarter found in an applicable financial statement. 


The income statement period month to consider. If not provided, defaults to the 


most recent available quarter found in an applicable financial statement. 


: "USD", 
d 
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D 
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"value": 0.4792, 
"target": 0.1, 
"pass": true 


"return on assets": { 
"value": 0.03, 
"target": 0.05, 
"pass": false 


D 


"return on equity": { 
"value": 0.2812, 
"target": 0.15, 
"pass": true 


D 


"debt to equity": { 
"value": 0.32, 
"target": 1.5, 
"pass": true 


D 


"debt ratio": { 
"value": 0.1067, 
"target": 0.05, 


"pass": 


bo 


true 


"asset turnover": { 
"value": 0.0626, 
"target": 1.0, 
"pass": false 


bo 


"net income": 11248.23, 
"total revenue": 23474.12, 
"total assets": 375000.0, 
"total liabilities": 40000.0, 
"total equity": 125000.0 


RESPONSE 


Field 


currency code 


profit margin 


value 


Description 


Currency code associated with monetary response values. 


Results for Profit Margin. 


The calculated value. 
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Field 


> 
< 
= target 


pass 


return_on_assets 


value 


target 


pass 


return_on_equity 


value 


target 


pass 


debt to equity 


value 


target 


pass 


debt ratio 


value 


target 


pass 


asset turnover 


value 


target 


pass 


Hydrogen Proton API Reference 


Description 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 


Results for Return on Assets. 


The calculated value. 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 


Results for Return on Equity. 


The calculated value. 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 


Results for Debt-to-Equity. 


The calculated value. 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 


Results for Debt Ratio. 


The calculated value. 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 


Results for Asset Turnover. 


The calculated value. 


The target value, as determined by ratio targets. 


If true, value is sufficient as compared to its target. 
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Field 


NAV Ill 


net_income 


total revenue 


total assets 


total liabilities 


total equity 


Hydrogen Proton API Reference 


Description 


The underlying net income used for the analysis. If net income is not provided 
in the request, this value is derived dynamically. 


The underlying total revenue used for the analysis. If total revenue is not 
provided in the request, this value is derived dynamically. 


The underlying total assets used for the analysis. If total assets is not 
provided in the request, this value is derived dynamically. 


The underlying total liabilities used for the analysis. If total liabilities is not 
provided in the request, this value is derived dynamically. 


The underlying total equity used for the analysis. If total equity is not 
provided in the request, this value is derived dynamically. 


NUCLEUS DATA DEPENDENCIES 


e Client 


e Financial Statement 


Financial Statement Analysis 


Financial Statement Analysis provides a structured view of a business’s accounting data over time. The 


analysis includes metrics from both the Income Statement (e.g. Net Income) and Balance Sheet (e.g. Total 


Assets). This tool is helpful for assessing trends in business activity via historical and statistical analysis, and 


also acts as an interface to view a high-level snapshot of business performance. 


HTTP REQUEST 


POST /business/financial_statement_analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" ^ 


«JH 
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"stat names": [ 
"total assets", 


Hydrogen Proton API Reference 


"client id": "e4a0dc1a-df02-4630-af44-1489f16598a5", 
"currency code": "USD", 


"total liabilities", 


"total equity", 


"total revenue", 


"net income" 


"accounting method": "accrual", 


"period type": "calendar", 


"period length": "quarterly", 


"period year": 2020, 


"period quarter": 1, 

"start date": "2020-05-31", 
"end date": "2020-08-31", 
"show history": true, 


"history frequency interval": "month" 


Lei 


ARGUMENTS 


Parameter 


client_id 
UUID 


business id 
UUID 


currency code 


string 


currency conversion 


string 


"https://[sandbox][api].hydrogenplatform 


Description 


The ID of a Nucleus Client that represents the business to be 
analyzed. Must have client type of firm. If one of client id or 
business id is not provided, the analysis will include data that is not 
linked to any client or business. 


The ID of a Nucleus Business that represents the business to be 
analyzed. If one of client id or business id is not provided, the 
analysis will include data that is not linked to any client or business. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Only records with this currency code will be considered. 
Defaults to USD if currency conversion is not provided. If 
currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Records will be converted from their original currency to 
the one indicated here. Conversions are supported both to and from 
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z 


Parameter 


start date 
date 


end date 
date 


statement type 


string 


stat names 


array[string] 


accounting method 


string, required 


period type 
string, conditionally required 


period length 


string 


period year 


integer 


period quarter 


integer 


Hydrogen Proton API Reference 
Description 


the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


Start date for balance sheet analysis. Defaults to the earliest financial 
statement date available. 


End date for balance sheet analysis. Defaults to today's date. 


The type of financial statement to include in the analysis. Value may 
be balance sheet, income statement, or all. Default to all. 
Please note that statement type and stat names both contribute 
to the scope of the analysis. 


Names of specific financial stats to include in the analysis. Values may 


be from the income statement ( total revenue, cogs, 

gross profit, operating income, total expenses, ebitda, 
net income), or the balance sheet (cash, total assets, 
total liabilities, total equity, accounts receivable, 
accounts payable ). If not provided, all stats within the scope of 
statement type are considered. 


The accounting method for the analysis. Value may be accrual or 
cash. Only financial statements with this accounting method are 
considered. 


The period type to consider for income statement analysis if 
statement type = income statement or any value in 

stat names falls under income statement. Value may be calendar 
or fiscal. 


The period length to consider for income statement analysis if 
statement type = income statement or any value in 

stat names falls under income statement. Value may be annual, 
quarterly, monthly, ytd, qtd,or mtd. Defaults to quarterly. 


Year to consider for income statement analysis if statement type = 
income statement orany value in stat names falls under income 
statement. If not provided, defaults to the most recent available year 
found in an applicable financial statement. 


Quarter to consider for income statement analysis if statement type 
= income statement or any value in stat names falls under 
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= Parameter 
> 
a 
z 


period_month 


integer 
history frequency interval 


string 


show history 


boolean 


Example Response 


"currency code": "USD", 


Hydrogen Proton API Reference 


IDescrépitete ment. If not provided, defaults to the most recent 
available quarter found in an applicable financial statement. 


Month to consider for income statement analysis if statement type 
- income statement orany value in stat names falls under 
income statement. If not provided, defaults to the most recent 
available month found in an applicable financial statement. 


The frequency of historical stat values for balance sheet analysis. 
Value can be one of day, week, month, quarter, or year. When 
Set to a value other than day , a historical entry is returned for the end 
of each corresponding period. For example, with a value of month, 
the last day of each month in the analysis period will be reflected in 
the stat history. Defaults to month . Only applicable when 


show history is true. 


Determines whether to return historical stat values for balance sheet 
analysis. Defaults to false. 


"accounting method": "accrual", 


"balance sheet": { 


"analysis start": "2020-05-31", 
"analysis end": "2020-08-31", 


"stats": [ 
{ 


"name": "total assets", 
"current value": 375000.0, 
"mean value": 309408.6, 
"median value": 300000.0, 


SA 
275000.0, 
"2020-06-29" 
{ 
375000.0, 
"2020-08-31" 


"min value" 
"value": 
"date": 

bo 

"max value": 
"value": 
"date": 

bo 

"change": { 
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"1 day": { 
"value": 25000.0, 
"percentage": 0.0714 


bo 

"7 day": { 
"value": 25000.0, 
"percentage": 0.0714 

bo 

"30 day": { 
"value": 25000.0, 
"percentage": 0.0714 

bo 

"60 day": { 
"value": 75000.0, 
"percentage": 0.25 

bo 

"90 day": { 
"value": 100000.0, 
"percentage": 0.3636 

bo 

"total": { 
"value": 100000.0, 
"percentage": 0.3636 

} 

} 
bo 
{ 
"name": "total equity", 


"current value": 125000.0, 
"mean value": 80645.16, 
"median value": 75000.0, 
"min value": ( 
"value": 65000.0, 
"date": "2020-06-29" 
J 
"max_value": { 
"value": 125000.0, 
"date": "2020-08-31" 
J 
"change": { 
"1 day": { 
"value": 25000.0, 
"percentage": 0.25 
bo 
"7 day": ( 
"value": 25000.0, 
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"percentage": 0.25 


ig 

"30 day": { 
"value": 25000.0, 
"percentage": 0.25 

J 

"60 day": { 
"value": 50000.0, 
"percentage": 0.6667 

bo 

"90 day": { 
"value": 60000.0, 
"percentage": 0.9231 

bo 

"total": { 
"value": 60000.0, 
"percentage": 0.9231 

} 

} 
bo 
{ 
"name": "total liabilities", 


"current value": 40000.0, 
"mean value": 51451.61, 
"median value": 50000.0, 
"min value": ( 
"value": 40000.0, 
"date": "2020-08-31" 
bo 
"max value": { 
"value": 60000.0, 
"date": "2020-06-29" 
bo 
"change": { 
"1 day": { 
"value": -5000.0, 
"percentage": -0.1111 


bo 
"7 day": { 
"value": -5000.0, 
"percentage": -0.1111 
bo 
"30 day": { 
"value": -5000.0, 
"percentage": -0.1111 
bo 
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= "60 day": { 
a "value": -10000.0, 
z "percentage": -0.2 
bo 
"90 day": { 


"value": -20000.0, 
"percentage": -0.3333 


bo 
"total": { 
"value": -20000.0, 
"percentage": -0.3333 
} 
} 
Ip 
"history": [ 
{ 
"date": "2020-05-31", 
"values": [ 
{ 
"name": "total assets", 
"value": 275000.0 
ko 
{ 
"name": "total liabilities", 
"value": 60000.0 
Yo 
d 
"name": "total equity", 
"value": 65000.0 
} 
] 
bo 
{ 
"date": "2020-06-30", 
"values": [ 
d 
"name": "total assets", 
"value": 300000.0 
bo 
{ 
"name": "total liabilities", 
"value": 50000.0 
bo 
{ 


"name": "total equity", 
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> 
A } 
= ] 
bo 
{ 
"date": "2020-07-31", 
"values": [ 
{ 
"name": "total assets", 


"value": 350000.0 


bo 
{ 
"name": "total liabilities", 
"value": 45000.0 
bo 
{ 
"name": "total equity", 
"value": 100000.0 
} 
] 
bo 
{ 
"date": "2020-08-31", 
"values": [ 
{ 
"name": "total assets", 
"value": 375000.0 
bo 
{ 
"name": "total liabilities", 
"value": 40000.0 
bo 
d 
"name": "total equity", 
"value": 125000.0 
} 
] 
} 


D 


"income statement": { 
"period length": "quarterly", 
"period type": "calendar", 
"statement details": { 
"statement date": "2020-03-31", 
"period year": 2020, 
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"period quarter": 1, 
"period month": null 

bo 

"previous statement details": { 
"statement date": "2019-12-31", 
"period year": 2019, 
"period quarter": 4, 
"period month": null 


Hydrogen Proton API Reference 


Lé 

"stats": 
{ 
Jo 
d 
} 

] 

} 
} 
RESPONSE 
Field 


currency_code 


accounting_method 


balance sheet 


analysis start 


[ 


"name": "total revenue", 
"value": 23474.12, 
"previous value": 19264.32, 
"change": { 
"value": 4209.8, 
"percentage": 0.2185 


"name": "net income", 
"value": 11248.23, 
"previous value": 9784.75, 
"change": { 
"value": 1463.48, 
"percentage": 0.1496 


Description 


Currency code associated with monetary response values. 


Accounting method associated with response values. 


Analytics on balance sheet stats. 


Start date of the analysis period. If start date was provided in 
the request, it is reflected here. If start date was not provided, 
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analysis end 


stats 


name 


current_value 


mean_value 


median_value 


min_value 


value 


date 


max_value 


value 


date 


change 


1_day 


value 


percentage 


7_day 


value 


Hydrogen Proton API Reference 


Description 


this value is derived dynamically. 


End date of the analysis. If end_date was provided in the 
request, it is reflected here. If end_date was not provided, this 
value is derived dynamically. 


Metrics on each stat included in the analysis. Each entry has the 
fields shown below. 


Name of the stat. 


Most recent stat value, as of the end of the analysis period. 


Mean stat value over the analysis period. 


Median stat value over the analysis period. 


Minimum stat value over the analysis period. 


Stat value. 


Effective date for stat value. 


Maximum stat value over the analysis period. 


Stat value. 


Effective date for stat value. 


Stat change metrics over various periods, as of the 
analysis end date. Only the change periods that are 
encapsulated in the analysis period are returned. 


Change over the past 1 day. 


Absolute change. 


Percentage change. 


Change over the past 7 days. 


Absolute change. 
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percentage 


30 day 


value 


percentage 


60 day 


value 


percentage 


90 day 


value 


percentage 


180 day 


value 


percentage 


365 day 


value 


percentage 


total 


value 


percentage 


history 


date 


Hydrogen Proton API Reference 


Description 


Percentage change. 


Change over the past 30 days. 


Absolute change. 


Percentage change. 


Change over the past 60 days. 


Absolute change. 


Percentage change. 


Change over the past 90 days. 


Absolute change. 


Percentage change. 


Change over the past 180 days. 


Absolute change. 


Percentage change. 


Change over the past 365 days. 


Absolute change. 


Percentage change. 


Change over the full analysis period. 


Absolute change. 


Percentage change. 


Historical stat data, with frequency dependent on the 
history frequency interval value passed in the request. 
Each entry has the fields shown below. 


Effective date for stat values. 
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Field 
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values 


name 


value 


income_statement 


period length 


period type 


statement details 


statement date 


period year 


period quarter 


period month 


previous statement details 


statement date 


period year 


period quarter 


period month 


stats 


name 


value 


Hydrogen Proton API Reference 


Description 


Historical values for each stat included in the analysis. Each entry 
has the fields shown below. 


Name of the stat. 


Historical stat value. 


Analytics on income statement stats. 


Periodicity of the analysis. 


Period type of the analysis. 


Details regarding the primary statement in the analysis. 


Recorded statement date. 


Year associated with the statement. 


Quarter associated with the statement, if period length is 
quarterly or qtd. 


Month associated with the statement, if period length is 
monthly or mtd. 


Details regarding the previous statement in the analysis. 


Recorded statement date. 


Year associated with the statement. 


Quarter associated with the statement, if period length is 
quarterly or qtd. 


Month associated with the statement, if period length is 
monthly or mtd. 


Metrics on each stat included in the analysis. Each entry has the 
fields shown below. 


Name of the stat. 


Stat value from the primary statement in the analysis. 
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= Field Description 
> 
< 
zZ previous_value Stat value from the previous statement in the analysis. 
change Stat change from the previous statement to the primary statement. 
value Absolute change. 
name Percentage change. 


NUCLEUS DATA DEPENDENCIES 


e Client 
e Financial Statement 


Invoice Analysis 


Invoice Analysis produces advanced analytics on invoice activity for a business. This includes a high-level 
summary of both receivable and payable invoices issued and paid, as well as information on outstanding 
invoices, current invoices, overdue invoices, and invoices coming due in configurable future time windows. It 
also highlights invoiced customers and suppliers, as well as individual invoices that may warrant a business’s 
attention. Use this service to gain valuable insights into both current and historical invoice activity. 


HTTP REQUEST 


POST /business/invoice_analysis 


Example Request 


curl -X POST -H “Authorization: Bearer <access_token>" \ 

-H "Content-Type: application/json" \ 

-d '( 
"client id": "9e0dd1c0-7669-47ff-9a32-b10434df36dd", 
"currency code": "USD", 
"start date": "2020-01-01", 
"end date": "2020-08-31", 
"history frequency interval": "month", 
"response limit": 1, 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 81/440 


8/3/23, 5:08 PM 


NAV Ill 


Hydrogen Proton API Reference 


"show history": true, 


"show outstanding invoices": true 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/business/invoice analy 


ARGUMENTS 


Parameter 


client id 
UUID 


business id 
UUID 


customer ids 
array[UUID] 


invoice ids 
array[UUID] 


currency code 


string 


currency conversion 


string 


Description 


The ID of a Nucleus Client that represents the business to be 
analyzed. Must have client type of firm. If one of client id, 
business id, customer ids,or invoice ids is not provided, the 


analysis will include data that is not linked to any client or business. 


The ID of a Nucleus Business that represents the business to be 
analyzed. If one of client id, business id, customer ids,or 
invoice ids is not provided, the analysis will include data that is not 
linked to any client or business. 


The ID(s) of Nucleus Contact(s) to be analyzed. A contact either is 
considered a customer if the is customer parameter is setto true, 
or is considered a supplier if the is supplier parameter is set to 
true. If one of client id, business id, customer ids,or 
invoice ids is not provided, the analysis will include data that is not 
linked to any client or business. 


The ID(s) of Nucleus Invoice(s) to be analyzed. If one of client id, 
business id, customer ids,or invoice ids is not provided, the 


analysis will include data that is not linked to any client or business. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Only records with this currency code will be considered. 
Defaults to USD if currency conversion is not provided. If 
currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Records will be converted from their original currency to 
the one indicated here. Conversions are supported both to and from 
the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 
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Parameter 


NAV Ill 


start_date 
date 


end_date 


date 


future_due_periods 


array[map] 


start 


integer 


end 


integer 
overdue_periods 
array[map] 

start 


integer 


end 


integer 
response_limit 
integer 
history frequency interval 


string 


show history 


boolean 


show outstanding invoices 


boolean 


Hydrogen Proton API Reference 
Description 
Start date for invoice analysis. Defaults to the earliest date of available 


data. If there is no underlying data found, start date defaults to one 
day prior to end date. 


End date for invoice analysis. Defaults to today's date. 


Periods in days relative to end date that apply to 
future due periods in the response. Defaults to show 30 day 
increments. Each entry has the fields shown below. Duplicate entries 
may not be passed. 


Start day of the period, such as 1. Must be greater than or equal to O. 


End day of the period, such as 30. Must be greater than or equal to 
start.Use null to indicate all integers greater than start. 


Periods in days relative to end date that apply to overdue periods 
in the response. Defaults to show 30 day increments. Each entry has 
the fields shown below. Duplicate entries may not be passed. 


Start day of the period, such as 1. Must be greater than or equal to 0. 


End day of the period, such as 30. Must be greater than or equal to 
start.Use null to indicate all integers greater than start. 


The maximum number of records to be returned in 
top overdue invoices, top overdue customers, 


top paid invoices, and top paid customers. 


The frequency of historical invoice data. Defaults to month . Only 
applicable when show history is true. 


If true, returns historical invoice data. Defaults to false. 


If true, returns details on all outstanding invoices. Defaults to 


false. 
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Example Response 


"currency code": "USD", 
"analysis start": "2020-01-01", 
"analysis end": "2020-08-31", 
"receivable": { 


"total_number_of_invoices": 9, 
"total_amount_invoiced": 74703.07, 
"total_amount_paid": 27089.85, 
"total_amount_unpaid": 47613.22, 
"paid summary": { 
"number of invoices": 2, 
"amount paid": 12500.0 
bo 
"outstanding summary": { 
"number of invoices": 7, 
"amount paid": 14589.85, 
"amount unpaid": 47613.22 
bo 
"current summary": { 
"number of invoices": 2, 
"amount paid": 683.29, 
"amount unpaid": 12077.2, 
"percent of outstanding": 0.2537 
bo 
"overdue summary": { 
"number of invoices": 5, 
"amount paid": 13906.56, 
"amount unpaid": 35536.02, 
"percent of outstanding": 0.7463 
bo 
"future due periods": | 
{ 
"start": 0, 
"end": 30, 
"number of invoices": 1, 
"amount paid": 683.29, 
"amount unpaid": 3644.26, 
"percent of current": 0.3017 


"start": 31, 
"end": 60, 
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"number of invoices": 1, 

"amount paid": 0, 

"amount unpaid": 8432.94, 
"percent of current": 0.6983 


NAV Ill 


bo 

{ 
"start": 61, 
"end": 90, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of current": 0.0 

bo 

{ 
"start": 91, 
"end": null, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of current": 0.0 

} 

L 
"overdue periods": [ 

{ 
"start": 1, 
"end": 30, 
"number of invoices": 2, 
"amount paid": 2750.0, 
"amount unpaid": 10571.24, 
"percent of overdue": 0.2975 

ko 

{ 
"start": 31, 
"end": 60, 
"number of invoices": 1, 
"amount paid": 1500.0, 
"amount unpaid": 6000.0, 
"percent of overdue": 0.1688 

bo 

{ 
"start": 61, 
"end": 90, 


"number of invoices": 1, 
"amount paid": 3000.0, 
"amount unpaid": 12000.0, 
"percent of overdue": 0.3377 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 85/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


NAV III 


"start": 91, 

"end": null, 
"number of invoices": 1, 
"amount paid": 6656.56, 
"amount unpaid": 6964.78, 
"percent of overdue": 0.196 


l 
"top_overdue_invoices": [ 
{ 

"invoice_id": "f83fc955-9509-46e0-9d8b-514b578e8351", 
"invoice_number": "3647031", 
"invoice date": "2020-05-12", 
"invoice due date": "2020-06-12", 
"days overdue": 80, 
"amount invoiced": 15000.0, 
"amount paid": 3000.0, 
"amount unpaid": 12000.0, 
"percent of overdue": 0.3377 


L 
"top overdue customers": [ 
{ 
"contact id": "c387c95c-657f-4334-3947-9590242ab742", 
"company name": "Cube Financial", 
"number of invoices": 2, 
"amount paid": 9656.56, 
"amount unpaid": 18964.78, 
"overdue periods": [ 
{ 
"start": 1, 
"end": 30, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of overdue": 0.0 


"start": 31, 

"end": 60, 
"number of invoices": 0, 
"amount paid": 0, 

"amount unpaid": 0, 
"percent of overdue": 0.0 
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= bo 
a ( 
= "start": 61, 
"end": 90, 
"number_of_invoices": 1, 
"amount paid": 3000.0, 
"amount unpaid": 12000.0, 
"percent of overdue": 0.6328 
bo 
{ 
"start": 91, 
"end": null, 
"number of invoices": 1, 
"amount paid": 6656.56, 
"amount unpaid": 6964.78, 
"percent of overdue": 0.3672 
} 
] 
} 
], 
"top paid invoices": [ 
{ 
"invoice id": "9dd7f0c2-5728-4a4f-9447-1c5c8d53c194", 
"invoice number": "3244929", 
"invoice date": "2020-02-01", 
"amount paid": 10000.0, 
"percent of paid": 0.8 
} 
], 
"top paid customers": [ 
{ 
"contact id": "b4407cfa-fbae-4cd9-9ad5-71c@bcdad286", 
"company name": "Gradient Entertainment", 
"number of invoices": 3, 
"amount paid": 14250.0 
} 
l 
"history": [ 
{ 
"period_start": "2020-01-01", 
"period_end": "2020-01-31", 
"amount_invoiced": 0.0, 
"amount paid": 0.0 
bo 
{ 


"period start": "2020-02-01", 
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= "period end": "2020-02-29", 
a "amount invoiced": 100900.0, 
z "amount paid": 0.0 
bo 
{ 
"period start": "2020-03-01", 
"period end": "2020-03-31", 
"amount invoiced": 0.0, 
"amount paid": 10000.0 
bo 
{ 
"period start": "2020-04-01", 
"period end": "2020-04-30", 
"amount invoiced": 13621.34, 
"amount paid": 0.0 
bo 
{ 
"period start": "2020-05-01", 
"period end": "2020-05-31", 
"amount invoiced": 15000.0, 
"amount paid": 1452.57 
bo 
{ 
"period start": "2020-06-01", 
"period end": "2020-06-30", 
"amount invoiced": 7500.0, 
"amount paid": 4783.92 
bo 
{ 
"period start": "2020-07-01", 
"period end": "2020-07-31", 
"amount invoiced": 15821.24, 
"amount paid": 4346.21 
bo 
{ 
"period start": "2020-08-01", 
"period end": "2020-08-31", 
"amount invoiced": 12760.49, 
"amount paid": 4007.15 
} 
Ip 
"outstanding invoices": [ 
{ 


"invoice id": "f83fc955-9509-46e0-9d8b-514b578e8351", 
"invoice number": "3647031", 
"invoice date": "2020-05-12", 
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"invoice due date": "2020-06-12", 
"days until due": null, 


NAV III 


"days overdue": 80, 

"is overdue": true, 
"number of payments": 1, 

"latest payment date": "2020-06-25", 
"amount invoiced": 15000.0, 

"amount paid": 3000.0, 

"amount unpaid": 12000.0 


"invoice id": "4af61b65-8499-49f8-8853-602e1b6f105d", 
"invoice number": "5240307", 
"invoice date": "2020-08-26", 
"invoice due date": "2020-10-26", 
"days until due": 56, 

"days overdue": null, 

"is overdue": false, 
"number of payments": 0, 

"Latest payment date": null, 
"amount invoiced": 8432.94, 
"amount paid": 0, 

"amount unpaid": 8432.94 


"invoice id": "bb26fdfb-0b3b-4ec1-b127-054b703bfa39", 
"invoice number": "4981774", 
"invoice date": "2020-07-26", 
"invoice due date": "2020-08-27", 
"days until due": null, 

"days overdue": 4, 

"is overdue": true, 
"number of payments": 0, 

"latest payment date": null, 
"amount invoiced": 8321.24, 
"amount paid": 0, 

"amount unpaid": 8321.24 


"invoice id": "00bef7eb-8127-4bff-ba60-eece19cf3bd7", 
"invoice number": "8600501", 

"invoice date": "2020-04-18", 

"invoice due date": "2020-05-18", 

"days until due": null, 

"days overdue": 105, 

"is overdue": true, 
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"number of payments": 4, 

"latest payment date": "2020-05-28", 
"amount invoiced": 13621.34, 

"amount paid": 6656.56, 

"amount unpaid": 6964.78 


"invoice id": "54cf6152-6de0-4e18-9e67-a1da359831a6f", 


"invoice number": "5861978", 
"invoice date": "2020-06-22", 
"invoice due date": "2020-07-22", 
"days until due": null, 

"days overdue": 40, 

"is overdue": true, 
"number of payments": 1, 

"latest payment date": "2020-07-31", 
"amount invoiced": 7500.0, 
"amount paid": 1500.0, 

"amount unpaid": 6000.0 


"invoice id": "bd6c3f2d-72cd-43ae-b3a7-c97c474fc39b", 


"invoice number": "8188898", 
"invoice date": "2020-08-01", 
"invoice due date": "2020-09-30", 
"days until due": 30, 

"days overdue": null, 

"is overdue": false, 
"number of payments": 1, 

"latest payment date": "2020-08-19", 
"amount invoiced": 4327.55, 
"amount paid": 683.29, 

"amount unpaid": 3644.26 


"invoice id": "fd895006-a54a-406b-9acf-21bc91e443e2", 


"invoice number": "9429762", 
"invoice date": "2020-07-16", 
"invoice due date": "2020-08-16", 
"days until due": null, 

"days overdue": 15, 

"is overdue": true, 
"number of payments": 1, 

"latest payment date": "2020-08-19", 
"amount invoiced": 5000.0, 

"amount paid": 2750.0, 
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"amount unpaid": 2250.0 
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bo 
"payable": { 

"total number of invoices": 3, 

"total amount invoiced": 48331.63, 

"total amount paid": 16425.84, 

"total amount unpaid": 31905.79, 

"paid summary": { 
"number of invoices": 1, 
"amount paid": 5000.0 

D 

"outstanding summary": { 
"number of invoices": 2, 
"amount paid": 11425.84, 
"amount unpaid": 31905.79 

D 

"current summary": { 
"number of invoices": 1, 
"amount paid": 6734.56, 
"amount unpaid": 18703.86, 
"percent of outstanding": 0.5862 

D 

"overdue summary": { 
"number of invoices": 1, 
"amount paid": 4691.28, 
"amount unpaid": 13201.93, 
"percent of outstanding": 0.4138 

D 


"future due periods": [ 
{ 

"start": 0, 

"end": 30, 
"number of invoices": 1, 
"amount paid": 6734.56, 
"amount unpaid": 18703.86, 
"percent of current": 1.0 


"start": 31, 

"end": 60, 
"number of invoices": 0, 
"amount paid": 0, 

"amount unpaid": 0, 
"percent of current": 0.0 
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"start": 61, 

"end": 90, 
"number of invoices": 0, 
"amount paid": 0, 

"amount unpaid": 9, 
"percent of current": 0.0 


"start": 91, 

"end": null, 
"number of invoices": 0, 
"amount paid": 0, 

"amount unpaid": 0, 
"percent of current": 0.0 


], 


"overdue periods": [ 
{ 

"start": 1, 
"end": 30, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of overdue": 0.0 


"start": 31, 

"end": 60, 
"number of invoices": 1, 
"amount paid": 4691.28, 
"amount unpaid": 13201.93, 
"percent of overdue": 1.0 


"start": 61, 

"end": 90, 
"number of invoices": 0, 
"amount paid": 0, 

"amount unpaid": 0, 
"percent of overdue": 0.0 


"start": 91, 
"end": null, 
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"number of invoices": 0, 
"amount paid": 0, 


NAV III 


"amount unpaid": 0, 
"percent of overdue": 0.0 


L 
"top overdue invoices": [ 
{ 

"invoice id": "d0f72049-61f7-4d2c-8799-05f2fea8ac1a", 
"invoice number": "973458", 
"invoice date": "2020-06-24", 
"invoice due date": "2020-07-07", 
"days overdue": 55, 
"amount invoiced": 17893.21, 
"amount paid": 4691.28, 
"amount unpaid": 13201.93, 
"percent of overdue": 1.0 


]; 


"top overdue suppliers": [ 
{ 

"contact id": "89b8d79c-7189-451b-bc18-fa17338c0ae7", 
"company name": "Vortex Solar", 
"number of invoices": 1, 
"amount paid": 4691.28, 
"amount unpaid": 13201.93, 
"overdue periods": [ 


{ 
"start": 1, 
"end": 30, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of overdue": 0.0 
bo 
{ 
"start": 31, 
"end": 60, 
"number of invoices": 1, 
"amount paid": 4691.28, 
"amount unpaid": 13201.93, 
"percent of overdue": 1.0 
bo 
{ 
"start": 61, 
"end": 90, 
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"number of invoices": 0, 
"amount paid": 0, 
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"amount unpaid": 0, 
"percent of overdue": 0.0 


bo 
{ 
"start": 91, 
"end": null, 
"number of invoices": 0, 
"amount paid": 0, 
"amount unpaid": 0, 
"percent of overdue": 0.0 
} 
] 
} 
L 
"top paid invoices": [ 
d 
"invoice id": "33989e4c-168f-4ecc-9c75-0c67e510d36e", 
"invoice number": "9346810", 
"invoice date": "2020-04-13", 
"amount paid": 5000.0, 
"percent of paid": 1.0 
} 
L 
"top paid suppliers": [ 
{ 
"contact id": "89b8d79c-7189-451b-bc18-fa17338c0ae7", 
"company name": "Vortex Solar", 
"number of invoices": 3, 
"amount paid": 16425.84 
} 
L 
"history": [ 
{ 
"period start": "2020-01-01", 
"period end": "2020-01-31", 
"amount invoiced": 0.0, 
"amount paid": 0.0 
bo 
{ 
"period start": "2020-02-01", 
"period end": "2020-02-29", 
"amount invoiced": 0.0, 
"amount paid": 0.0 
bo 
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= { 
z "period_start": "2020-03-01", 
< "period_end": "2020-03-31", 
"amount invoiced": 0.0, 
"amount paid": 0.0 
bo 
{ 
"period start": "2020-04-01", 
"period end": "2020-04-30", 
"amount invoiced": 5000.0, 
"amount paid": 0.0 
Yo 
d 
"period start": "2020-05-01", 
"period end": "2020-05-31", 
"amount invoiced": 0.0, 
"amount paid": 0.0 
bo 
{ 
"period start": "2020-06-01", 
"period end": "2020-06-30", 
"amount invoiced": 17893.21, 
"amount paid": 0.0 
bo 
{ 
"period start": "2020-07-01", 
"period end": "2020-07-31", 
"amount invoiced": 25438.42, 
"amount paid": 11425.84 
bo 
{ 
"period start": "2020-08-01", 
"period end": "2020-08-31", 
"amount invoiced": 0.0, 
"amount paid": 0.0 
} 
l 
"outstanding invoices": [ 
{ 


"invoice id": "165c8134-1105-43ec-a070-d8a68a1b5667", 
"invoice number": "6843265", 

"invoice date": "2020-07-12", 

"invoice due date": "2020-09-20", 

"days until due": 20, 

"days overdue": null, 

"is overdue": false, 


https://www.hydrogenplatform.com/docs/proton/v 1/#Introduction 95/440 


8/3/23, 5:08 PM 


NAV Ill 
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"number of payments": 1, 
"latest payment date": "2020-07-25", 
"amount invoiced": 25438.42, 


"amount paid": 6734.56, 
"amount unpaid": 18703.86 


"invoice id": "d0f72049-61f7-4d2c-8799-05f2feaB8ac1a", 


"invoice number": "973458", 
"invoice date": "2020-06-24", 
"invoice due date": "2020-07-07", 


"number of payments": 1, 


"latest payment date": "2020-07-01", 
"amount invoiced": 17893.21, 


"amount unpaid": 13201.93 


bo 

{ 
"days until due": null, 
"days overdue": 55, 
"is overdue": true, 
"amount paid": 4691.28, 

3 

] 
} 
} 
RESPONSE 
Field 


currency_code 


analysis start 


analysis end 


receivable 


total number of invoices 


total amount invoiced 


Description 


Currency code associated with monetary response values. 
Start date of the analysis period. If start date was provided in 
the request, it is reflected here. If start date was not provided, 


this value is derived dynamically. 


End date of the analysis period. If end date was provided in the 
request, it is reflected here. If end date was not provided, this 
value is derived dynamically. 


Invoice data for receivable invoices from customers. 


Total number of invoices issued in the analysis period. 


Total amount invoiced in the analysis period. 
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Field 


NAV Ill 


total_amount_paid 


total amount unpaid 


paid summary 


number of invoices 


amount paid 


outstanding summary 


number of invoices 


amount paid 


amount unpaid 


current summary 


number of invoices 


amount paid 


amount unpaid 


percent of outstanding 


overdue summary 


number of invoices 


amount paid 


amount unpaid 


percent of outstanding 


future due periods 
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Description 


Total amount paid in the analysis period. 


Total amount unpaid in the analysis period. 


Summary of invoices that are paid in full. 


Number of paid invoices. 


Amount paid on paid invoices. 


Summary of invoices that are outstanding. 


Number of outstanding invoices. 


Amount paid on outstanding invoices. 


Amount unpaid on outstanding invoices. 


Summary of outstanding invoices that are current. 


Number of current invoices. 


Amount paid on current invoices. 


Amount unpaid on current invoices. 


Amount unpaid on current invoices as a percentage of amount 
unpaid on all outstanding invoices. 


Summary of outstanding invoices that are overdue. 


Number of overdue invoices. 


Amount paid on overdue invoices. 


Amount unpaid on overdue invoices. 


Amount unpaid on overdue invoices as a percentage of amount 


unpaid on all outstanding invoices. 


Future periods representing the number of days until current 
invoices will become due, as of the analysis end date. If 
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Field 


start 


end 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_current 


overdue_periods 


start 


end 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_overdue 


top_overdue_invoices 
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Description 


future_due_periods is not provided in the request, 30-day 
intervals will be returned. Each entry has the fields shown below. 


Start day of the period. 


End day of the period. 


Number of current invoices that will become due in the period. 


Amount paid on current invoices that will become due in the period. 


Amount unpaid on current invoices that will become due in the 
period. 


Amount unpaid on current invoices that will become due in the 
period as a percentage of amount unpaid on all current invoices. 


Periods representing the number of days that overdue invoices 
have been past due, as of the analysis end date. If 
overdue_periods is not provided in the request, 30-day intervals 
will be returned. Each entry has the fields shown below. 


Start day of the period. 


End day of the period. 


Number of overdue invoices that have been past due for a number 
of days within the period. 


Amount paid on overdue invoices that have been past due for a 
number of days within the period. 


Amount unpaid on overdue invoices that have been past due for a 
number of days within the period. 


Amount unpaid on overdue invoices that have been past due for a 
number of days within the period as a percentage of the amount 
unpaid on all overdue invoices. 


List of the top overdue invoices. Returns up to a maximum number 
of records specified in response_limit . Each entry has the fields 
shown below. 
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Field 


NAV Ill 


invoice_id 


invoice_number 


invoice date 


invoice due date 


days overdue 


amount invoiced 


amount paid 


amount unpaid 


percent of overdue 


top overdue customers 


contact id 


company name 


number of invoices 


amount paid 


amount unpaid 


overdue periods 


start 


end 


Hydrogen Proton API Reference 


Description 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Due date of the invoice. 


Number of days the invoice has been overdue. 


Amount of the invoice. 


Amount paid on the invoice. 


Amount unpaid on the invoice. 


Amount unpaid on the invoice as a percentage of the amount 
unpaid on all overdue invoices. 


List of the top overdue customers. Returns up to a maximum 
number of records specified in response limit. Each entry has 
the fields shown below. 


ID of the Nucleus Contact that represents the customer. 


Company name for the customer. 


Number of the customer's overdue invoices. 


Amount paid on the customer's overdue invoices. 


Amount unpaid on the customer's overdue invoices. 


Periods representing the number of days that the customer's 
overdue invoices have been past due. If overdue periods is not 
provided in the request, 30-day intervals will be returned. Each 
entry has the fields shown below. 


Start day of the period. 


End day of the period. 
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Field 


NAV Ill 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_overdue 


top paid invoices 


invoice id 


invoice number 


invoice date 


amount paid 


percent of paid 


top paid customers 


contact id 


company name 


number of invoices 


amount paid 


history 
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Description 


Number of the customer's overdue invoices that have been past 
due for a number of days within the period. 


Amount paid on the customer's overdue invoices that have been 
past due for a number of days within the period. 


Amount unpaid on the customer's overdue invoices that have been 
past due for a number of days within the period. 


Amount unpaid on the customer's overdue invoices that have been 
past due for a number of days within the period as a percentage of 
the amount unpaid on all of the customer's overdue invoices. 


List of the top paid invoices. Returns up to a maximum number of 
records specified in response limit.Each entry has the fields 
shown below. 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Amount paid on the invoice. 


Amount paid on the invoice as a percentage of the amount paid on 
all paid invoices. 


List of the top paid customers. Returns up to a maximum number of 
records specified in response limit.Each entry has the fields 


shown below. 

ID of the Nucleus Contact that represents the customer. 
Company name for the customer. 

Number of the customer's paid invoices. 

Amount paid on the customer's paid invoices. 

Historical invoice data, with frequency dependent on the 


history frequency interval value passed in the request. Each 
entry has the fields shown below. 
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Field 


NAV Ill 


period start 


period end 


amount invoiced 


amount paid 


outstanding invoices 


invoice id 


invoice number 


invoice date 


invoice due date 


days until due 


days overdue 


is overdue 


number of payments 


latest payment date 


amount invoiced 


amount paid 


amount unpaid 


payable 


total number of invoices 


total amount invoiced 
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Description 


Period start date. 


Period end date. 


Amount invoiced in the period. 


Amount paid in the period. 


Each entry has the fields shown below. 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Due date of the invoice. 


As of the analysis end date, the number of days until the invoice 
due date. Will be null if is overdue is true. 


As of the analysis end date, the number of days that the invoice has 
been outstanding since the invoice due date. Will be nu11 if 


is overdue is false. 


If true , the invoice is overdue. If false, the invoice is current. 


Number of payments made on the invoice. 


Latest date a payment was made on the invoice. 


Amount of the invoice. 


Amount paid on the invoice. 


Amount unpaid on the invoice. 


Invoice data for payable invoices from suppliers. 


Total number of invoices issued in the analysis period. 


Total amount invoiced in the analysis period. 
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Field 


NAV Ill 


total_amount_paid 


total amount unpaid 


paid summary 


number of invoices 


amount paid 


outstanding summary 


number of invoices 


amount paid 


amount unpaid 


current summary 


number of invoices 


amount paid 


amount unpaid 


percent of outstanding 


overdue summary 


number of invoices 


amount paid 


amount unpaid 


percent of outstanding 


future due periods 
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Description 


Total amount paid in the analysis period. 


Total amount unpaid in the analysis period. 


Summary of invoices that are paid in full. 


Number of paid invoices. 


Amount paid on paid invoices. 


Summary of invoices that are outstanding. 


Number of outstanding invoices. 


Amount paid on outstanding invoices. 


Amount unpaid on outstanding invoices. 


Summary of outstanding invoices that are current. 


Number of current invoices. 


Amount paid on current invoices. 


Amount unpaid on current invoices. 


Amount unpaid on current invoices as a percentage of amount 
unpaid on all outstanding invoices. 


Summary of outstanding invoices that are overdue. 


Number of overdue invoices. 


Amount paid on overdue invoices. 


Amount unpaid on overdue invoices. 


Amount unpaid on overdue invoices as a percentage of amount 


unpaid on all outstanding invoices. 


Future periods representing the number of days until current 
invoices will become due, as of the analysis end date. If 
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Field 


start 


end 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_current 


overdue_periods 


start 


end 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_overdue 


top_overdue_invoices 
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Description 


future_due_periods is not provided in the request, 30-day 
intervals will be returned. Each entry has the fields shown below. 


Start day of the period. 


End day of the period. 


Number of current invoices that will become due in the period. 


Amount paid on current invoices that will become due in the period. 


Amount unpaid on current invoices that will become due in the 
period. 


Amount unpaid on current invoices that will become due in the 
period as a percentage of amount unpaid on all current invoices. 


Periods representing the number of days that overdue invoices 
have been past due, as of the analysis end date. If 
overdue_periods is not provided in the request, 30-day intervals 
will be returned. Each entry has the fields shown below. 


Start day of the period. 


End day of the period. 


Number of overdue invoices that have been past due for a number 
of days within the period. 


Amount paid on overdue invoices that have been past due for a 
number of days within the period. 


Amount unpaid on overdue invoices that have been past due for a 
number of days within the period. 


Amount unpaid on overdue invoices that have been past due for a 
number of days within the period as a percentage of the amount 
unpaid on all overdue invoices. 


List of the top overdue invoices. Returns up to a maximum number 
of records specified in response_limit . Each entry has the fields 
shown below. 
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Field 


NAV Ill 


invoice_id 


invoice_number 


invoice date 


invoice due date 


days overdue 


amount invoiced 


amount paid 


amount unpaid 


percent of overdue 


top overdue suppliers 


contact id 


company name 


number of invoices 


amount paid 


amount unpaid 


overdue periods 


start 


end 


Hydrogen Proton API Reference 


Description 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Due date of the invoice. 


Number of days the invoice has been overdue. 


Amount of the invoice. 


Amount paid on the invoice. 


Amount unpaid on the invoice. 


Amount unpaid on the invoice as a percentage of the amount 
unpaid on all overdue invoices. 


List of the top overdue suppliers. Returns up to a maximum number 
of records specified in response limit. Each entry has the fields 


shown below. 


ID of the Nucleus Contact that represents the supplier. 


Company name for the supplier. 


Number of the supplier's overdue invoices. 


Amount paid on the supplier's overdue invoices. 


Amount unpaid on the supplier's overdue invoices. 


Periods representing the number of days that the supplier's overdue 
invoices have been past due. If overdue periods is not provided 
in the request, 30-day intervals will be returned. Each entry has the 
fields shown below. 


Start day of the period. 


End day of the period. 
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Field 


NAV Ill 


number_of_invoices 


amount_paid 


amount_unpaid 


percent_of_overdue 


top paid invoices 


invoice id 


invoice number 


invoice date 


amount paid 


percent of paid 


top paid suppliers 


contact id 


company name 


number of invoices 


amount paid 


history 
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Description 


Number of the supplier's overdue invoices that have been past due 
for a number of days within the period. 


Amount paid on the supplier's overdue invoices that have been past 
due for a number of days within the period. 


Amount unpaid on the supplier's overdue invoices that have been 
past due for a number of days within the period. 


Amount unpaid on the supplier's overdue invoices that have been 
past due for a number of days within the period as a percentage of 
the amount unpaid on all of the supplier's overdue invoices. 


List of the top paid invoices. Returns up to a maximum number of 
records specified in response limit.Each entry has the fields 
shown below. 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Amount paid on the invoice. 


Amount paid on the invoice as a percentage of the amount paid on 
all paid invoices. 


List of the top paid suppliers. Returns up to a maximum number of 
records specified in response limit.Each entry has the fields 


shown below. 

ID of the Nucleus Contact that represents the supplier. 
Company name for the supplier. 

Number of the supplier's paid invoices. 

Amount paid on the supplier's paid invoices. 

Historical invoice data, with frequency dependent on the 


history frequency interval value passed in the request. Each 
entry has the fields shown below. 
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Field 


NAV Ill 


period start 


period end 


amount invoiced 


amount paid 


outstanding invoices 


invoice id 


invoice number 


invoice date 


invoice due date 


days until due 


days overdue 


is overdue 


number of payments 


latest payment date 


amount invoiced 


amount paid 


amount unpaid 


NUCLEUS DATA DEPENDENCIES 


e Client 
e Contact 
e Invoice 


Hydrogen Proton API Reference 


Description 


Period start date. 


Period end date. 


Amount invoiced in the period. 


Amount paid in the period. 


Each entry has the fields shown below. 


ID of the Nucleus Invoice. 


Number of the invoice. 


Date the invoice was issued. 


Due date of the invoice. 


As of the analysis end date, the number of days until the invoice 
due date. Will be null if is overdue is true. 


As of the analysis end date, the number of days that the invoice has 
been outstanding since the invoice due date. Will be nu11 if 


is overdue is false. 


If true , the invoice is overdue. If false, the invoice is current. 


Number of payments made on the invoice. 


Latest date a payment was made on the invoice. 


Amount of the invoice. 


Amount paid on the invoice. 


Amount unpaid on the invoice. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


106/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 


* Invoice Payment 


NAV Ill 


Decision Tree Result 


Returns the model_id or allocation_id by traversing the decision tree and finding the corresponding leaf 


node for the answer ids provided in the client response. 


HTTP REQUEST 


POST /decision tree result 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


xd 
"entity type": "model", 
"answers": [ 
{ 
"answer id": "2fcec30e-fad1-4845-a507-100c5deaeef3" 
} 
] 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/decision tree result" 
d p 
ARGUMENTS 
Parameter Description 


entity type The entity to which the answers correspond. The value can be model or allocation. 


string 


answers An array of objects, each with an answer provided in relation to the entity. 
array[map] 


answer id The ID of the answer being provided. 
UUID 
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a Example Response 
z 
i 
"entity type": "model", 
"entity id": "33fd99ce-3d28-46d7-a727-46b1b694fac1" 
} 
RESPONSE 
Field Description 


entity type The entity to which the answers correspond. The value can be model id or 


allocation id. 


entity id The ID of the entity, as a result of systemically traversing the decision tree. 


NUCLEUS DATA DEPENDENCIES 


e Allocation 

* Model 

* Decision Tree 

e Node 

« Node Relationship 
e Client 

* Client Response 


e Answer 


Financial Planning 


Annuity Calculator 


When planning for retirement or other financial outcomes, a fixed annuity allows an investor to receive a series 
of payments over a given period of time in the future. This tool analyzes fixed annuities and solves for a variety 
of relevant variables including the annuity amount, the investor's initial balance, ongoing contributions to the 
annuity, the accumulation horizon, and the decumulation horizon. 


Annuity Amount 
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= This service helps determine the annuity amount that is attainable based on the details provided. 


NAV 


HTTP REQUEST 


POST /annuity calculator/annuity amount 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" ^ 
-H "Content-Type: application/json" \ 
-d '( 
"portfolio return": 0.1, 
"initial balance": 2000, 
"accumulation horizon": 3, 
"decumulation horizon": 2, 
"annuity frequency interval": "year", 
"inflation rate": 0.02, 
"tax rate": 0.25, 
"deposit schedule": ( 
"deposit amount": 500, 


"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
} 
}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/annuity calculator/annui 
d > 
ARGUMENTS 
Parameter Description 
portfolio return The annualized rate of return of the portfolio. 


float, reguired 


accumulation horizon The number of years until the commencement of annuity 
integer, reguired payments. 
decumulation horizon The number of years that annuity payments last. 


integer, required 


annuity frequency interval The period interval that relates to annuity amount. Must be 
string one of year, quarter, month, week, or day. Defaults to 
year. 
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Parameter 


NAV Ill 


initial balance 
float 


inflation rate 
float 


tax_rate 
float 


deposit schedule 


map 


deposit amount 
float 


deposit frequency interval 


string 


adjust deposit for inflation 
boolean 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Example Response 


"annuity amount": 1753.96, 


Hydrogen Proton API Reference 


Description 


The starting balance in the annuity plan, prior to any periodic 
contributions. Defaults to 9. 


The annualized inflation rate to apply to portfolio return. 
Defaults to @. 


The tax rate to apply to annuity_amount . Defaults to @. 


The schedule of ongoing deposits to be made during the 
accumulation horizon. Includes the fields shown below. 


The periodic value of the deposit. Must be greater than or equal 
to 0. Defaults to 9. 


The unit of time associated with deposit_amount. Must be one 
of year, quarter, month, week, or day. Defaults to year. 


If true, deposit_amount will be adjusted over time based on 
inflation_rate. Defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 
initial_balance. If initial_balance is not provided, we 
will try to use account_ids and/or 
aggregation_account_ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial_balance. If initial_balance is not provided, we 
will try to use account_ids and/or 
aggregation_account_ids to derive this value instead. 


"annuity frequency interval": "year", 
"total earnings": 1482.95, 
"total contributions": 1530.2, 


"cumulative annuity amount": 5013.15, 
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"total taxes": 1671.05, 
"return details": { 
"Ms À 
"period earnings": 0, 


NAV Ill 


"period contribution": 0, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2000 

D 

"EX 
"period earnings": 200, 
"period contribution": 500, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 200, 
"cumulative contributions": 500, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2700 

bo 

"ES A 
"period earnings": 270, 
"period contribution": 510, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 470, 
"cumulative contributions": 1010, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 3480 

D 

WEI 
"period earnings": 348, 
"period contribution": 520.2, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 818, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 4348.2 


D 
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Hydrogen Proton API Reference 


"period earnings": 434.82, 
"period contribution": 0, 


"period withdrawal": 2481.76, 
"period tax": 827.25, 
"cumulative earnings": 1252.82, 


"cumulative contributions": 1530.2, 
"cumulative withdrawals": 2481.76, 
"cumulative tax": 827.25, 


"ending balance": 2301.26 


"cumulative earnings": 1482.95, 


"cumulative contributions": 1530.2, 


"cumulative withdrawals": 5013.15, 


bo 

"p". 1 
"period earnings": 230.13, 
"period contribution": 0, 
"period withdrawal": 2531.39, 
"period tax": 843.8, 
"cumulative tax": 1671.05, 
"ending balance": 9 

} 

} 
} 
RESPONSE 
Field 


annuity amount 


annuity frequency interval 


total earnings 


total contributions 


cumulative annuity amount 


total taxes 


Description 


The periodic annuity amount. 


The frequency at which annuity amount is drawn from the 
portfolio. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount received from the annuity over the course of the 
plan. 


The total taxes paid on annuity payments over 
decumulation horizon. 
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NAV III 


Field 


return_details 


period earnings 


period_contribution 


period withdrawal 


period tax 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative tax 


ending balance 


NUCLEUS DATA DEPENDENCIES 


Account 

Portfolio 

Portfolio Asset Size 
Aggregation Account 


Aggregation Account Balance 


Initial Balance 


Hydrogen Proton API Reference 


Description 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 


the beginning of each period, before contributions are made. 


The deposit made for this period. 


The withdrawal made for this period. 


The tax amount for this period. 


The cumulative investment earnings made up to and including this 


period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 
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This service helps determine the initial balance that an investor needs in order to satisfy the annuity details 


NAV Ill 


provided. 
HTTP REQUEST 
POST /annuity_calculator/initial_balance 
Example Request 
curl -X POST -H "Authorization: Bearer «access token»" V 
-H "Content-Type: application/json" ^ 
A aa 
"portfolio return": 0.1, 
"accumulation horizon": 3, 
"decumulation horizon": 2, 
"annuity amount": 3000, 
"annuity frequency interval": "year", 
"inflation rate": 0.02, 
"tax rate": 0.25, 
"deposit schedule": ( 
"deposit amount": 500, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
} 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/annuity calculator/initi 
d > 
ARGUMENTS 
Parameter Description 
portfolio_return The annualized rate of return of the portfolio. 


float, required 


accumulation_horizon The number of years until the commencement of annuity 
integer, required payments. 
decumulation_horizon The number of years that annuity payments last. 


integer, required 


annuity_amount The amount of the annuity, represented in today’s dollars. 
float, conditional requirement 
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zi 
z 
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Parameter 


annuity frequency interval 


string 


inflation rate 


float 


tax rate 
float 


deposit schedule 


map 


deposit amount 
float 


deposit frequency interval 


string 


adjust deposit for inflation 


boolean 


Example Response 


"initial balance": 4320.83, 
"total earnings": 2723.53, 


Hydrogen Proton API Reference 


Description 


The period interval that relates to annuity amount. Must be 
one of year, quarter, month, week, or day. Defaults to 


year. 


The annualized inflation rate to apply to portfolio return. 
Defaults to @. 


The tax rate to apply to annuity_amount . Defaults to 0. 


The schedule of ongoing deposits to be made during the 


accumulation horizon. Includes the fields shown below. 


The periodic value of the deposit. Must be greater than or equal 
to 0. Defaults to @. 


The unit of time associated with deposit_amount. Must be one 
of year, quarter, month, week, or day. Defaults to year. 


If true, deposit_amount will be adjusted over time based on 
inflation_rate. Defaults to true. 


"total contributions": 1530.2, 
"cumulative annuity amount": 8574.56, 


"total taxes": 2858.19, 
"return details": { 
"o": f 


"period earnings": 0, 


"period contribution": 0, 


"period withdrawal": 0, 


"period tax": 0, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 


"cumulative withdrawals": 0, 


"cumulative tax": 0, 
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"ending balance": 4320.83 

D 

" 1 " : 1 


"period earnings": 432.08, 


NAV III 


"period contribution": 500, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 432.08, 
"cumulative contributions": 500, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 5252.91 

D 

SEI 
"period earnings": 525.29, 
"period contribution": 510, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 957.37, 
"cumulative contributions": 1010, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 6288.21 

) 

"Sy Y 
"period earnings": 628.82, 
"period contribution": 520.2, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 1586.2, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 7437.23 

D 

"4": { 
"period earnings": 743.72, 
"period contribution": 0, 
"period withdrawal": 4244.83, 
"period tax": 1414.94, 
"cumulative earnings": 2329.92, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 4244.83, 
"cumulative tax": 1414.94, 
"ending balance": 3936.12 


D 
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"cumulative earnings": 2723.53, 


"cumulative contributions": 1530.2, 
"cumulative withdrawals": 8574.56, 


= "p". { 

a "period earnings": 393.61, 

= "period_contribution": ®, 
"period withdrawal": 4329.73, 
"period tax": 1443.24, 
"cumulative tax": 2858.19, 
"ending balance": 9 

} 
} 
} 
RESPONSE 
Field 


initial balance 


total earnings 


total contributions 


cumulative annuity amount 


total taxes 


return details 


period earnings 


period contribution 


period withdrawal 


Description 


The starting balance in the annuity plan, prior to any periodic 


contributions. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount received from the annuity over the course of the 
plan. 


The total taxes paid on annuity payments over 
decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions are made. 


The deposit made for this period. 


The withdrawal made for this period. 
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zi 
z 


Field 


period tax 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative tax 


ending balance 


Deposit Amount 


Hydrogen Proton API Reference 


Description 


The tax amount for this period. 


The cumulative investment earnings made up to and including this 


period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 


This service helps determine the recurring amount to be contributed over the accumulation horizon, in order to 


satisfy the annuity details provided. 


HTTP REQUEST 


POST /annuity calculator/deposit amount 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


-d '{ 


"portfolio_return": 0.1, 
"initial_balance": 2000, 


"accumulation_horizon": 3, 


"decumulation horizon": 2, 


"annuity amount": 3000, 


"annuity frequency interval": "year", 


"inflation rate": 
"tax rate": 0.25, 


0.02, 
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"deposit schedule": { 


Hydrogen Proton API Reference 


"deposit frequency interval": "year", 


"adjust deposit for inflation": true 


} 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/annuity calculator/depos 


ARGUMENTS 


Parameter 


portfolio return 


float, required 


accumulation horizon 


integer, required 


decumulation horizon 


integer, required 


annuity amount 


float, required 

annuity frequency interval 
string 

initial balance 


float 


inflation rate 
float 


tax rate 
float 


deposit schedule 


map 


deposit frequency interval 


string 


Description 


The annualized rate of return of the portfolio. 


The number of years until the commencement of annuity 
payments. 


The number of years that annuity payments last. 


The amount of the annuity, represented in today's dollars. 


The period interval that relates to annuity amount. Must be 
one of year, quarter, month, week, or day. Defaults to 


year. 


The starting balance in the annuity plan, prior to any periodic 
contributions. Defaults to 0. 


The annualized inflation rate to apply to portfolio return. 
Defaults to @. 


The tax rate to apply to annuity_amount . Defaults to @. 
The schedule of deposits to be made during the 
accumulation horizon. Includes the fields shown below. 
The period interval to be used in relation to the 


deposit_amount . Must be one of year, quarter, month, 


week , or day. Defaults to year. 
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= Parameter Description 
z 
x: adjust deposit for inflation |f true,the deposit amount will be increased by 
boolean inflation rate. Defaults to true. 
account_ids The ID(s) of the Nucleus account(s) used to derive 
array[UUID] initial_balance. If initial_balance is not provided, we 


will try to use account_ids and/or 
aggregation_account_ids to derive this value instead 


aggregation_account_ids The ID(s) of the Nucleus aggregation account(s) used to derive 
array[UUID] initial_balance. If initial_balance is not provided, we 
will try to use account_ids and/or 


aggregation_account_ids to derive this value instead 


Example Response 


"deposit amount": 1415.97, 
"deposit frequency interval": "year", 
"total earnings": 2241.12, 
"total contributions": 4333.44, 
"cumulative annuity amount": 8574.56, 
"total taxes": 2858.19, 
"return details": { 
"a": { 
"period earnings": 0, 
"period contribution": 0, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2000 
J 
"AT. d 
"period earnings": 200, 
"period contribution": 1415.97, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 200, 
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"cumulative contributions": 1415.97, 
"cumulative withdrawals": 0, 


NAV III 


"cumulative tax": 0, 
"ending balance": 3615.97 

D 

Far: d 
"period earnings": 361.6, 
"period contribution": 1444.29, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 561.6, 
"cumulative contributions": 2860.26, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 5421.86 

D 

"Si d 
"period earnings": 542.19, 
"period contribution": 1473.18, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 1103.78, 
"cumulative contributions": 4333.44, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 7437.23 

bo 

"4": { 
"period earnings": 743.72, 
"period contribution": 0, 
"period withdrawal": 4244.83, 
"period tax": 1414.94, 
"cumulative earnings": 1847.51, 
"cumulative contributions": 4333.44, 
"cumulative withdrawals": 4244.83, 
"cumulative tax": 1414.94, 
"ending balance": 3936.12 

D 

ZS of 
"period earnings": 393.61, 
"period contribution": 0, 
"period withdrawal": 4329.73, 
"period tax": 1443.24, 
"cumulative earnings": 2241.12, 
"cumulative contributions": 4333.44, 
"cumulative withdrawals": 8574.56, 
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"cumulative tax": 2858.19, 


"ending balance": 9 
} 
} 
} 
RESPONSE 
Field 


deposit amount 


deposit frequency interval 


total earnings 


total contributions 


cumulative annuity amount 


total taxes 


return details 


period earnings 


period contribution 


period withdrawal 


period tax 


cumulative contributions 


Description 


The amount to be deposited per period. 


The period interval to be used in relation to the deposit amount. 
Defaults to year . 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount received from the annuity over the course of the 
plan. 


The total taxes paid on annuity payments over 
decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 


the beginning of each period, before contributions are made. 


The deposit made for this period. 


The withdrawal made for this period. 


The tax amount for this period. 


The cumulative deposits made up to and including this period. 
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zi 
z 


Field Description 
cumulative withdrawals The cumulative withdrawals made up to and including this period. 
cumulative tax The cumulative taxes up to and including this period. 
ending balance The ending balance, inclusive of earnings and contributions for the 


current period. 


Account 

Portfolio 

Portfolio Asset Size 
Aggregation Account 


Aggregation Account Balance 


NUCLEUS DATA DEPENDENCIES 


Account 

Portfolio 

Portfolio Asset Size 
Aggregation Account 
Aggregation Account Balance 


Decumulation Horizon 


This service helps determine the time horizon over which an annuity can persist, based on the details 


provided. 


HTTP REQUEST 


POST /annuity calculator/decumulation horizon 


Example Request 


curl -X POST -H "Authorization: Bearer «access token?" ^ 
-H "Content-Type: application/json" \ 
-d '( 
"portfolio return": 0.1, 
"initial balance": 2000, 


"accumulation horizon": 3, 
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"annuity amount": 3000, 
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"annuity frequency interval": "year", 


"inflation rate": 0.02, 


"tax rate": 0.25, 


"deposit schedule": ( 


"deposit amount": 500, 


"deposit frequency interval": "year", 


"adjust deposit for inflation": 


) 


true 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/annuity calculator/decun 


ARGUMENTS 


Parameter 


portfolio return 


float, required 


accumulation horizon 


integer, required 


annuity amount 


float, required 

annuity frequency interval 
string 

initial balance 


float 


inflation rate 
float 


tax rate 
float 


deposit schedule 


map 


deposit amount 
float 


Description 


The annualized rate of return of the portfolio. 


The number of years until the commencement of annuity 
payments. 


The amount of the annuity, represented in today's dollars. 
The period interval that relates to annuity amount. Must be 
one of year, quarter, month, week, or day. Defaults to 


year. 


The starting balance in the annuity plan, prior to any periodic 
contributions. Defaults to 0. 


The annualized inflation rate to apply to portfolio return. 
Defaults to ®. 


The tax rate to apply to annuity amount. Defaults to 0. 


The schedule of ongoing deposits to be made during the 


accumulation horizon. Includes the fields shown below. 


The periodic value of the deposit. Must be greater than or equal 
to 0. Defaults to 9. 
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= Parameter 

> 

x 

zZ deposit_frequency_interval 


string 


adjust_deposit_for_inflation 


boolean 


account_ids 
array[UUID] 


aggregation_account_ids 
array[UUID] 


Example Response 


"decumulation horizon": { 
"years": 1, 
"months": 1, 
"days": 12 

bo 

"total earnings": 1259.94, 


Hydrogen Proton API Reference 


Description 


The unit of time associated with deposit amount. Must be one 
of year, quarter, month, week, or day. Defaults to year. 


If true, deposit amount will be adjusted over time based on 
inflation rate. Defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 

initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


"total contributions": 1530.2, 


"cumulative annuity amount": 4790.14, 


"total taxes": 1596.71, 
"return details": { 
"o": f 


"period earnings": 0, 


"period contribution": 0, 


"period withdrawal": 0, 


"period tax": 0, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 

"ending balance": 2000 


bo 
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n" 1 n" $ { 
"period earnings": 200, 


NAV III 


"period contribution": 500, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 200, 
"cumulative contributions": 500, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2700 

D 

SE 
"period earnings": 270, 
"period contribution": 510, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 470, 
"cumulative contributions": 1010, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 3480 

D 

"ari. À 
"period earnings": 348, 
"period contribution": 520.2, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 818, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 4348.2 

D 

"4": d 
"period earnings": 434.82, 
"period contribution": 0, 
"period withdrawal": 4244.83, 
"period tax": 1414.94, 
"cumulative earnings": 1252.82, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 4244.83, 
"cumulative tax": 1414.94, 
"ending balance": 538.19 

) 

"5": d 


"period earnings": 7.12, 
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"period contribution": 0, 
"period withdrawal": 545.31, 
"period tax": 181.77, 


"cumulative earnings": 1259.94, 


"cumulative contributions": 1530.2, 
"cumulative withdrawals": 4790.14, 


"cumulative tax": 


1596.71, 


"ending balance": 9 


} 
} 
} 
RESPONSE 
Field 


decumulation horizon 


years 


months 


days 


total earnings 


total contributions 


cumulative annuity amount 


total taxes 


return details 


period earnings 


Description 


The time horizon over which annuity payments persist. 


The number of years in the decumulation horizon. 


The number of months in the decumulation horizon. 


The number of days in the decumulation horizon. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount received from the annuity over the course of the 
plan. 


The total taxes paid on annuity payments over 
decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions are made. 
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Field 


period contribution 


period withdrawal 


period tax 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative tax 


ending balance 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

e Portfolio Asset Size 

* Aggregation Account 

e Aggregation Account Balance 


Accumulation Horizon 


This service helps determine the accumulation horizon (i.e. the time period until annuity payments begin) that 


Hydrogen Proton API Reference 


Description 


The deposit made for this period. 


The withdrawal made for this period. 


The tax amount for this period. 


The cumulative investment earnings made up to and including this 


period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 


is needed in order to satisfy the annuity details provided. 


HTTP REQUEST 


POST /annuity calculator/accumulation horizon 
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a Example Request 
2 
curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" N 
-d '{ 

"portfolio return": 0.1, 

"initial balance": 2000, 

"decumulation horizon": 2, 

"annuity amount": 3000, 

"annuity frequency interval": "year", 

"inflation rate": 0.02, 

"tax rate": 0.25, 

"deposit schedule": ( 
"deposit amount": 500, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 

} 

)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/annuity calculator/accun 
4 > 
ARGUMENTS 
Parameter Description 
portfolio_return The annualized rate of return of the portfolio. 


float, required 


decumulation_horizon The number of years that annuity payments last. 


integer, required 


annuity_amount The amount of the annuity, represented in today’s dollars. 
float, required 


annuity_frequency_interval The period interval that relates to annuity_amount . Must be 

string one of the following: year, quarter, month, week. Defaults 
to year. 

initial_balance The starting balance in the annuity plan, prior to any periodic 

float contributions. Defaults to @. 

inflation rate The annualized inflation rate to apply to portfolio return. 

float Defaults to @. 
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Parameter 


NAV Ill 


tax_rate 
float 


deposit_schedule 


map 


deposit_amount 
float 


deposit_frequency_interval 


string 


adjust deposit for inflation 
boolean 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Example Response 


"accumulation horizon": { 
"years": 6, 
"months": @, 
"days": 0 

J 


"total earnings": 3632.85, 


Hydrogen Proton API Reference 


Description 


The tax rate to apply to annuity amount. Defaults to 0. 


The schedule of ongoing deposits to be made during the 
accumulation horizon. Includes the fields shown below. 


The periodic value of the deposit. Must be greater than or equal 
to 0. Defaults to 9. 


The unit of time associated with deposit amount. Must be one 


of year, quarter, month, week , or day. Defaults to year. 


If true, deposit amount will be adjusted over time based on 
inflation rate. Defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 

initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 


aggregation account ids to derive this value instead 


"total contributions": 3467.25, 
"cumulative annuity amount": 9100.11, 


"total taxes": 3033. 
"return details": { 
"o": f 


37; 


"period earnings": 0, 
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"period contribution": 0, 
"period withdrawal": 0, 


NAV Ill 


"period tax": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2000 

D 

ee 
"period earnings": 200, 
"period contribution": 500, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 200, 
"cumulative contributions": 500, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 2700 

D 

Far À 
"period earnings": 270, 
"period contribution": 510, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 470, 
"cumulative contributions": 1010, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 3480 

D 

"ue d 
"period earnings": 348, 
"period contribution": 520.2, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 818, 
"cumulative contributions": 1530.2, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 4348.2 

n 

"4": { 
"period earnings": 434.82, 
"period contribution": 530.6, 
"period withdrawal": 0, 
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"period tax": 0, 
"cumulative earnings": 1252.82, 


NAV III 


"cumulative contributions": 2060.8, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 5313.62 

bo 

"5": 4d 
"period earnings": 531.36, 
"period contribution": 541.22, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 1784.18, 
"cumulative contributions": 2602.02, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 6386.2 

D 

"6": { 
"period earnings": 638.62, 
"period contribution": 552.04, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 2422.8, 
"cumulative contributions": 3154.06, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 7576.86 

J 

"X À 
"period_earnings": 3.01, 
"period contribution": 313.19, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 2425.81, 
"cumulative contributions": 3467.25, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 7893.06 

D 

"8": { 
"period earnings": 789.31, 
"period contribution": 0, 
"period withdrawal": 4505, 
"period tax": 1501.67, 
"cumulative earnings": 3215.12, 
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"cumulative contributions": 3467.25, 
"cumulative withdrawals": 4505, 

"cumulative tax": 1501.67, 


"ending balance": 4177.37 


NAV Ill 


bo 
"go" a f 
"period earnings": 417.74, 
"period contribution": 0, 
"period withdrawal": 4595.1, 
"period tax": 1531.7, 
"cumulative earnings": 3632.85, 
"cumulative contributions": 3467.25, 
"cumulative withdrawals": 9100.11, 
"cumulative tax": 3033.37, 
"ending balance": @ 
} 
} 
} 
RESPONSE 
Field Description 
accumulation horizon The time horizon until the commencement of annuity payments. 
years The number of years in the accumulation horizon. 
months The number of months in the accumulation horizon. 
days The number of days in the accumulation horizon. 
total earnings The total earnings generated over the horizon. 
total contributions The total contributions added over the horizon. 
cumulative annuity amount The total amount received from the annuity over the course of the 
plan. 
total taxes The total taxes paid on annuity payments over 


decumulation horizon. 
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NAV III 


Field Description 


return_details Portfolio return information over the length of the horizon, broken 
down by period. 


period_earnings The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions are made. 


period_contribution The deposit made for this period. 

period_withdrawal The withdrawal made for this period. 

period_tax The tax amount for this period. 

cumulative_earnings The cumulative investment earnings made up to and including this 
period. 


cumulative contributions The cumulative deposits made up to and including this period. 


cumulative withdrawals The cumulative withdrawals made up to and including this period. 
cumulative_tax The cumulative taxes up to and including this period. 
ending balance The ending balance, inclusive of earnings and contributions for the 


current period. 


NUCLEUS DATA DEPENDENCIES 


Account 

Portfolio 

Portfolio Asset Size 
Aggregation Account 


Aggregation Account Balance 
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Education Planning Calculator 


NAV Ill 


When planning for a future education expense, users face common questions when deciding where or when 
to attend. This tool helps in the decision process with three different endpoints to solve for the following 
parameters: deposit amount, percent of costs covered, and total annual cost. With these calculators, the user 
will be able to determine how much needs to be saved to attend a particular school, or what schools would be 
affordable given their financial circumstances. For all calculators, deposits are assumed to continue through 
the decumulation phase. 


Deposit Amount 


A calculator to help plan for an education goal by showing the user the amount that needs to be deposited for 
a given period. 


HTTP REQUEST 


POST /education_calculator/deposit_amount 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
dictu 
"initial balance": 5000, 
"accumulation horizon": 3, 
"decumulation horizon": 4, 
"total annual cost": 40000, 
"portfolio return": 0.06, 
"percent of costs covered": 0.78, 
"education inflation rate": 0.05, 
"general inflation rate": 0.02, 
"tax rate": 0.33, 
"deposit schedule": ( 


"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
} 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/education calculator/c 
d p 
ARGUMENTS 
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Parameter 


accumulation_horizon 


integer, required 


decumulation_horizon 


integer, required 


total_annual_cost 


float, required 


portfolio return 


float, required 


percent of costs covered 
float 


initial balance 
float 


education inflation rate 
float 


general inflation rate 
float 


tax rate 
float 


deposit schedule 


map 


deposit frequency interval 


string 


adjust deposit for inflation 


boolean 


account ids 
array[UUID] 


Hydrogen Proton API Reference 
Description 


The amount of years until funds are needed to pay for an 
education expense. 


The number of years to pay the total annual cost. 


The total cost paid per year for the education goal, represented 
in today's dollars. 


The portfolio return for the length of the 


accumulation horizon and decumulation horizon. 


The percentage of total annual cost to be paid for. If 
excluded, defaults to 1. 


The amount currently saved for the education goal. If excluded, 
defaults to 0 . 


The inflation rate attributed to total annual cost . If 
excluded, defaults to 8.05. 


The rate used to increase deposits for inflation. If excluded, 
defaults to 8.02. 


The tax rate to apply to investments upon removal from the 
portfolio. If excluded, defaults to @. 


The deposit schedule for the education goal. 


The period interval to be used in relation to the 
deposit amount. The value may be one of the following: 
year, quarter, month, or week. If excluded, defaults to 


year. 


If true, the deposits should be increased over time with the 
rate of inflation. If excluded, defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 

initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 
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A 
z 


Parameter Description 
aggregation account ids The ID(s) of the Nucleus aggregation account(s) used to derive 
array[UUID] initial balance. If initial balance is not provided, we 


will try to use account ids and/or 
aggregation account ids to derive this value instead 


Example Response 


"deposit amount": 37564.93, 
"deposit frequency interval": "year", 
"projected accumulation savings": 127860.79, 
"total earnings": 28506.82, 
"total contributions": 279268.34, 
"total cost": 209559.36, 
"total taxes": 103215.8, 
"return details": { 
"a": { 
"period earnings": 0, 
"period contribution": 0, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 
bo 
"dte 
"period earnings": 300, 
"period contribution": 37564.93, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 37564.93, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 42864.93 
J 
cane f 
"period_earnings": 2571.9, 
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"period contribution": 38316.23, 
"period withdrawal": 0, 


NAV III 


"period taxes": 0, 

"cumulative earnings": 2871.9, 
"cumulative contributions": 75881.16, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 

"ending balance": 83753.06 


D 

"3 s T 
"period earnings": 5025.18, 
"period contribution": 39082.55, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 7897.08, 
"cumulative contributions": 114963.71, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 127860.79 

D 

"4": d 
"period earnings": 7671.65, 
"period contribution": 39864.2, 
"period withdrawal": -48620.25, 
"period taxes": -23947.29, 
"cumulative earnings": 15568.73, 
"cumulative contributions": 154827.92, 
"cumulative withdrawals": -48620.25, 
"cumulative taxes": -23947.29, 
"ending balance": 102829.11 

D 

"S S d 
"period earnings": 6169.75, 
"period contribution": 40661.49, 
"period withdrawal": -51051.26, 
"period taxes": -25144.65, 
"cumulative earnings": 21738.47, 
"cumulative contributions": 195489.41, 
"cumulative withdrawals": -99671.51, 
"cumulative taxes": -49091.94, 
"ending balance": 73464.43 

bo 

"b i À 


"period earnings": 4407.87, 
"period contribution": 41474.72, 
"period withdrawal": -53603.83, 
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"period taxes": -26401.88, 


z "cumulative earnings": 26146.34, 

= "cumulative contributions": 236964.13, 
"cumulative withdrawals": -153275.34, 
"cumulative taxes": -75493.82, 


"ending balance": 39341.3 


J 

"EU: d 
"period earnings": 2360.48, 
"period contribution": 42304.21, 
"period withdrawal": -56284.02, 
"period taxes": -27721.98, 
"cumulative earnings": 28506.82, 
"cumulative contributions": 279268.34, 
"cumulative withdrawals": -209559.36, 
"cumulative taxes": -103215.8, 
"ending balance": 

} 

} 
} 
RESPONSE 
Field 


deposit amount 


deposit frequency interval 


projected accumulation savings 


total earnings 


total contributions 


total cost 


total taxes 


return details 


Description 


The deposit amount to meet the education goal. 


The period interval associated with deposit amount. 


The projected balance at the end of accumulation horizon. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 


decumulation horizon. 


The total taxes paid on withdrawals over 


decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 
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Field 


period earnings 


period contribution 


period withdrawal 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative taxes 


ending balance 


NUCLEUS DATA DEPENDENCIES 


* Account 

* Portfolio 

* Portfolio Asset Size 

e Aggregation Account 

e Aggregation Account Balance 


Percent of Costs Covered 


A calculator to help plan for an education goal by solving for the percentage of the total cost that the user can 


afford. 


Hydrogen Proton API Reference 


Description 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 
withdrawals are made. 


The deposit made for this period. 


The withdrawal made for this period. 


The taxes paid during this period. 


The cumulative investment earnings made up to and including 


this period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes paid up to and including this period. 


The ending balance, inclusive of earnings and contributions for 
the current period. 
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HTTP REQUEST 


z POST /education_calculator/percent_covered 
Z 
Example Request 
curl -X POST -H “Authorization: Bearer <access_token>" \ 
-H "Content-Type: application/json" \ 
-d '( 
"initial_balance": 5000, 
"accumulation horizon": 3, 
"decumulation horizon": 4, 
"total annual cost": 40000, 
"portfolio return": 0.06, 
"education inflation rate": 0.05, 
"general inflation rate": 0.02, 
"tax rate": 0.33, 
"deposit schedule": ( 
"deposit amount": 4000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
} 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/education calculator/f 
4 > 
ARGUMENTS 
Parameter Description 
accumulation_horizon The amount of years until funds are needed to pay for an 
integer, required education expense. 
decumulation_horizon The number of years to pay the total_annual_cost. 


integer, required 


total_annual_cost The total cost paid per year for the education goal, represented 
float, required in today’s dollars. 

portfolio_return The portfolio return for the length of the 

float, required accumulation_horizon and decumulation_horizon. 
initial_balance The amount currently saved for the education goal. If excluded, 
float defaults to 0. 
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Parameter 


NAV Ill 


education_inflation_rate 
float 


general inflation rate 
float 


tax rate 
float 


deposit schedule 


map 


deposit amount 
float 


deposit frequency interval 


string 


adjust deposit for inflation 


boolean 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Example Response 


"achievable cost": 5047.62, 
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Description 


The inflation rate attributed to total_annual_cost. If 
excluded, defaults to 8.05. 


The rate used to increase deposits for inflation. If excluded, 
defaults to 8.02. 


The tax rate to apply to investments upon removal from the 
portfolio. If excluded, defaults to @. 


The deposit schedule for the education goal. 


The amount deposited per a given period & number of intervals. 
Deposits are assumed to continue through the length of 
accumulation horizon and decumulation_horizon. If 


excluded, defaults to 8. 


The period interval to be used in relation to the 

deposit amount. The value may be one of the following: 
year, quarter, month, or week. If excluded, defaults to 
year. 


If true, the deposits should be increased over time with the 
rate of inflation. If excluded, defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 

initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 


aggregation account ids to derive this value instead. 
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"target cost": 40000, 
"percent of costs covered": 0.1262, 


NAV III 


"projected accumulation savings": 18935.88, 
"total earnings": 4732.09, 
"total contributions": 29737.13, 
"total cost": 26444.38, 
"total taxes": 13024.84, 
"return details": { 
"a": { 
"period earnings": 0, 
"period contribution": 0, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 
D 
ule Y 
"period earnings": 300, 
"period contribution": 4000, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 4000, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 9300 
D 
nary | 
"period earnings": 558, 
"period contribution": 4080, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 858, 
"cumulative contributions": 8080, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 13938 
D 
E d 
"period earnings": 836.28, 
"period contribution": 4161.6, 
"period withdrawal": 0, 
"period taxes": 0, 
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"an : 
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"cumulative earnings": 1694.28, 
"cumulative contributions": 12241.6, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 

"ending balance": 18935.88 


{ 

"period earnings": 1136.15, 

"period contribution": 4244.83, 
"period withdrawal": -6135.41, 
"period taxes": -3021.92, 

"cumulative earnings": 2830.43, 
"cumulative contributions": 16486.43, 
"cumulative withdrawals": -6135.41, 
"cumulative taxes": -3021.92, 

"ending balance": 15159.54 


{ 

"period earnings": 909.57, 

"period contribution": 4329.73, 
"period withdrawal": -6442.18, 
"period taxes": -3173.01, 

"cumulative earnings": 3740.01, 
"cumulative contributions": 20816.16, 
"cumulative withdrawals": -12577.59, 
"cumulative taxes": -6194.93, 

"ending balance": 10783.65 


{ 

"period earnings": 647.02, 

"period contribution": 4416.32, 
"period withdrawal": -6764.29, 
"period taxes": -3331.66, 

"cumulative earnings": 4387.02, 
"cumulative contributions": 25232.48, 
"cumulative withdrawals": -19341.88, 
"cumulative taxes": -9526.6, 

"ending balance": 5751.04 


{ 

"period earnings": 345.06, 

"period contribution": 4504.65, 
"period withdrawal": -7102.5, 

"period taxes": -3498.25, 

"cumulative earnings": 4732.09, 
"cumulative contributions": 29737.13, 
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= "cumulative withdrawals": -26444.38, 
a "cumulative taxes": -13024.84, 
= "ending balance": | 
} 
} 
} 
RESPONSE 
Field Description 


achievable cost 


target_cost 


percent of costs covered 


projected accumulation savings 


total earnings 


total contributions 


total cost 


total taxes 


return details 


period earnings 


period contribution 


period withdrawal 


The annual cost that can be covered, expressed in today's 
dollars. 


The total annual cost input representing the target annual 
goal amount. 


The percentage of target cost that can be covered. 


The projected balance at the end of accumulation horizon. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 


decumulation horizon. 


The total taxes paid on withdrawals over 


decumulation horizon. 


Portfolio return information over the length of the horizon, broken 


down by period. 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 


withdrawals are made. 


The deposit made for this period. 


The withdrawal made for this period. 
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Field 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative taxes 


ending balance 


NUCLEUS DATA DEPENDENCIES 


Account 

Portfolio 

Portfolio Asset Size 
Aggregation Account 


Aggregation Account Balance 


Total Annual Cost 


Hydrogen Proton API Reference 


Description 


The taxes paid during this period. 


The cumulative investment earnings made up to and including 
this period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes paid up to and including this period. 


The ending balance, inclusive of earnings and contributions for 
the current period. 


A calculator to help plan for an education goal by solving for the total annual cost that a user could afford. 


HTTP REQUEST 


POST /education calculator/annual cost 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


sd ^r 


"initial balance": 5000, 
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"accumulation horizon": 3, 


"decumulation horizon": 4, 


NAV Ill 


"portfolio return": 0.06, 
"percent of costs covered": 1, 
"education inflation rate": 0.05, 
"general inflation rate": 0.02, 
"tax rate": 0.33, 
"deposit schedule": ( 
"deposit amount": 4000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
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)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/education calculator/e 


ARGUMENTS 


Parameter 


accumulation horizon 


integer, required 


decumulation horizon 


integer, required 


portfolio return 


float, required 


percent of costs covered 
float 


initial balance 
float 


education inflation rate 
float 


general inflation rate 
float 


tax rate 
float 


Description 


The amount of years until funds are needed to pay for an 
education expense. 


The number of years to pay the total annual cost. 


The portfolio return for the length of the 


accumulation horizon and decumulation horizon. 


The percentage of total annual cost to be paid for. If 
excluded, defaults to 1. 


The amount currently saved for the education goal. If excluded, 
defaults to 0. 


The inflation rate attributed to total annual cost . If 
excluded, defaults to 0.05 . 


The rate used to increase deposits for inflation. If excluded, 
defaults to 0.02. 


The tax rate to apply to investments upon removal from the 
portfolio. If excluded, defaults to 0 . 
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> 

x 

zZ deposit_schedule 
map 


deposit_amount 
float 


deposit_frequency_interval 
string 


adjust_deposit_for_inflation 


boolean 


account_ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Example Response 


Hydrogen Proton API Reference 


Description 


The deposit schedule for the education goal. 


The amount deposited per a given period & number of intervals. 
Deposits are assumed to continue through the length of 
accumulation horizon and decumulation horizon . If 
excluded, defaults to 9. 


The period interval to be used in relation to the 
deposit amount. The value may be one of the following: 
year, quarter, month, or week. If excluded, defaults to 


year. 


If true, the deposits should be increased over time with the 
rate of inflation. If excluded, defaults to true. 


The ID(s) of the Nucleus account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 


aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


"total annual cost": 6135.41, 
"total annual cost adjusted": 5047.62, 
"projected accumulation savings": 18935.88, 
"total earnings": 4732.09, 
"total contributions": 29737.13, 
"total cost": 26444.38, 
"total taxes": 13024.84, 
"return details": { 
"a": { 
"period earnings": 0, 
"period contribution": 0, 
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"period withdrawal": 0, 
"period taxes": 0, 


NAV III 


"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 

D 

SS q 
"period earnings": 300, 
"period contribution": 4000, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 4000, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 9300 

D 

HE 
"period earnings": 558, 
"period contribution": 4080, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 858, 
"cumulative contributions": 8080, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 13938 

D 

"ar {d 
"period_earnings": 836.28, 
"period_contribution": 4161.6, 
"period_withdrawal": 0, 
"period_taxes": 0, 
"cumulative earnings": 1694.28, 
"cumulative contributions": 12241.6, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 18935. 88 

D 

"4": { 
"period earnings": 1136.15, 
"period contribution": 4244.83, 
"period withdrawal": -6135.41, 
"period taxes": -3021.92, 
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"cumulative earnings": 2830.43, 
"cumulative contributions": 16486.43, 
"cumulative withdrawals": -6135.41, 
"cumulative taxes": -3021.92, 

"ending balance": 15159.54 


{ 

"period earnings": 909.57, 

"period contribution": 4329.73, 
"period withdrawal": -6442.18, 
"period taxes": -3173.01, 

"cumulative earnings": 3740.01, 
"cumulative contributions": 20816.16, 
"cumulative withdrawals": -12577.59, 
"cumulative taxes": -6194.93, 

"ending balance": 10783.65 


{ 

"period earnings": 647.02, 

"period contribution": 4416.32, 
"period withdrawal": -6764.29, 
"period taxes": -3331.66, 

"cumulative earnings": 4387.02, 
"cumulative contributions": 25232.48, 
"cumulative withdrawals": -19341.88, 
"cumulative taxes": -9526.6, 

"ending balance": 5751.04 


{ 

"period earnings": 345.06, 

"period contribution": 4504.65, 
"period withdrawal": -7102.5, 

"period taxes": -3498.25, 

"cumulative earnings": 4732.09, 
"cumulative contributions": 29737.13, 
"cumulative withdrawals": -26444.38, 
"cumulative taxes": -13024.84, 


"ending balance": @ 
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Field 


NAV Ill 


total_annual_cost 


total_annual_cost_adjusted 


projected_accumulation_savings 


total_earnings 


total_contributions 


total_cost 


total taxes 


return details 


period earnings 


period contribution 


period withdrawal 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


Hydrogen Proton API Reference 


Description 


The total education cost per year that can be afforded. 


The total education cost per year that can be afforded, 
represented in today's dollars. 


The projected balance at the end of accumulation horizon. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 


decumulation horizon. 


The total taxes paid on withdrawals over 


decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 


withdrawals are made. 


The deposit made for this period. 


The withdrawal made for this period. 


The taxes paid during this period. 


The cumulative investment earnings made up to and including 


this period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 
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= Field Description 

> 

< 

= cumulative_taxes The cumulative taxes paid up to and including this period. 
ending balance The ending balance, inclusive of earnings and contributions for 


the current period. 


NUCLEUS DATA DEPENDENCIES 


* Account 

e Portfolio 

e Portfolio Asset Size 
e Aggregation Account 


* Aggregation Account Balance 


Emergency Fund Calculator 


An emergency fund refers to a pool of money a user can rely on if they experience a loss of income. This fund 
should be able to cover all necessary expenses that the user would have to continue paying. The tool allows 
for the flexibility to use pre-set expense fields, or utilize an area for custom expenses. After specifying the 
number of months of expenses the emergency fund should cover, the calculator returns a total 
recommendation along with a plan to save for the total recommended amount in a variety of horizon intervals. 


HTTP REQUEST 


POST /emergency fund calculator 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" ^ 
-H "Content-Type: application/json" \ 
-d '( 
"emergency fund duration": 12, 
"housing cost": 1650, 
"utility payments": 60, 
"telecom payments": 50, 
"insurance payments": 0, 
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"debt payments": ®, 
"transportation costs": 150, 
"food costs": 1500, 

"other expenses": 


{ 


NAV Ill 


"entertainment": 50, 
"daycare": 150 
bo 
"current emergency fund balance": 15000, 
"interest rate": 0.015, 
"savings horizon": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 
"frequency unit": "month" 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/emergency fund calculatc 


ARGUMENTS 


Parameter 


emergency fund duration 


integer, required 


housing cost 
float 


utility payments 
float 


telecom payments 
float 


insurance payments 
float 


debt payments 
float 


transportation costs 
float 


food costs 
float 


Description 


The number of periods (defined in frequency unit ) that the 
emergency fund will last. 


The user's housing costs, such as payments for rent, mortgage, 
maintenance, etc. If excluded, defaults to ©. 


The user's utility payments, such as electricity, water, gas, etc. If 
excluded, defaults to 8. 


The user's telecom payments, such as internet, cell phone, cable, 
etc. If excluded, defaults to ®. 


The user's payments for insurance, such as auto, home, 
motorcycle, etc. If excluded, defaults to 0. 


The user's debt payments, such as credit cards and loans. If 
excluded, defaults to ®. 


The user's transportation costs, such as gasoline, car payments, 
etc. If excluded, defaults to ®. 


The user's food costs, such as groceries, restaurants, etc. If 
excluded, defaults to ®. 
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Parameter 


NAV Ill 


other_expenses 
map 


category_name 


string, required 


amount 


float, required 


current emergency fund balance 
float 


interest rate 
float 


savings horizon 


array 


frequency_unit 


string 


client_id 


UUID 


lookback_periods 


integer 


Hydrogen Proton API Reference 


Description 


A field to add any other expense type to be included in the 
emergency fund. If excluded, no additional expenses are included 
in the calculation. 


The category name for each additional expense. 


The user's total expense for each given category name. 


The user's current balance of their emergency fund. If excluded, 
defaults to 8. 


The annualized interest rate earned on the 

current emergency fund balance used to calculate the 
recommended savings amount. The interest rate is 
converted from annual rate to the appropriate frequency defined 
in frequency unit. If excluded, defaults to 8. 


The periods in the savings horizon to be used in the 
recommended savings schedule. The period frequency is defined 
by frequency unit. If excluded, defaults to [3, 6, 9, 12, 
15, 18, 21, 24]. 


The frequency unit that applies to emergency fund duration, 
all expenses, savings horizon and saving schedule. The 
value may be one of the following: year, quarter, month, 
two weeks or week. If excluded, defaults to month . 


The ID of a Nucleus client used to derive one or more of the 
following based on the client's spending history: housing cost, 
utility payments, telecom payments, 

insurance payments, debt payments, 
transportation costs, and food costs . If raw values for 
any of these optional parameters are not provided, we will use 
client id to try to derive those values instead. 


Number of periods to analyze when deriving expenses using a 
client id. The unit of time associated with each period is 
based on frequency unit , and expenses are averaged across 
all periods. Defaults to 3. 
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Parameter 


account_ids 
array[UUID] 


aggregation_account_ids 


array[UUID] 


Example Response 


Hydrogen Proton API Reference 


Description 


The ID(s) of the Nucleus account(s) used to derive 

current emergency fund balance . If 

current emergency fund balance is not provided, we will try 
to use account ids and/or aggregation account ids to 
derive those values instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
current emergency fund balance. If 

current emergency fund balance is not provided, we will try 
to use account ids and/or aggregation account ids to 
derive those values instead. 


"emergency fund recommendation": 43320, 


"savings schedule": { 


i 


2 
3 
4 
5 
"g" 
7 
8 
9 


"10": 
AM. s 
ae 
"ag 
"14": 
Eu 
"Ae 
MATS 
"18"; 
"39": 
"20"; 
al: 
"22: 
aag 


28320.0, 


14151 
9428. 
7066. 
5649 
4705. 
4030 
3524. 
3131. 


2816. 
2558. 
2343. 
2162. 
2006. 
1871. 
1753. 
1649.4 
1556. 
1473. 
1399. 
1331. 
1270. 
1214. 


EH 
29, 
83, 


.95, 


37, 


.67, 
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NAV Ill 
we 


RESPONSE 


Field Description 


emergency_fund_recommendation The total amount recommended for the user's emergency fund. 


savings_schedule The amount the user would need to save in order to achieve their 
emergency fund goal in a predefined amount of time. 


NUCLEUS DATA DEPENDENCIES 


e Client 

* Account 

e Portfolio 

e Portfolio Asset Size 

* Aggregation Account 

* Aggregation Account Balance 

« Aggregation Account Transaction 


e 
Only one of account id, aggregation account id, allocation id, model id,and portfolio id 
should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Life Insurance Needs Calculator 


When deciding to purchase life insurance, users face a common question: how much life insurance do | need? 
While some in the industry rely on broad rules of thumb (such as a multiple of household income), this 
calculator uses a discounted cash flow approach. Once the user provides expense and other pertinent 
information, the calculator returns the life insurance need, a breakdown of expenses by category, and return 
details broken down by period. 


HTTP REQUEST 
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POST /life insurance/needs calculator 


NAV III 


Example Request 


curl -X POST -H "Authorization: Bearer «access token?" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"mortgage_balance": 200000, 
"other_debt": 100000, 
"interest rate": 0.06, 
"end of life expenses": 10000, 
"existing life insurance": 50000, 
"liquid assets": 400000, 
"general inflation rate": 0.02, 
"education inflation rate": 0.05, 
"tax rate": 0.25, 
"benefit amount rounding": 6, 
"margin of error": 0.05, 
"children education config": 


[ 


"current age": 17, 
"education config": 


[ 


"start age": 18, 
"end age": 22, 
"total annual cost": 40000 


} 
IF 


"income config": 


[ 


"annual net take home pay": 50000, 
"percentage of income covered": 1, 
"income benefit duration": 5 


} 
IF 


"beneficiary bequest config": 
[ 


"years until bequest": 1, 
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"bequest amount": 10000, 


"bequest duration": 5 


] 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/life insurance/needs calci 


ARGUMENTS 


Parameter 


mortgage balance 


float, conditioanl requirement 


other debt 


integer, conditional requirement 


interest rate 


float, required 


end of life expenses 
float 


existing life insurance 
float 


liquid assets 
float 


general inflation rate 
float 


education inflation rate 
float 


tax rate 


float 


benefit amount rounding 


integer 


Description 


The user's outstanding mortgage balance. 


Other outstanding debt. 


The annual interest rate earned once the benefit amount is 
received. 


Burial, funeral, and other end-of-life expenses to be paid at the 
first period. If excluded, defaults to @. 


Existing life insurance currently held by the insuree. If excluded, 
defaults to 0 . 


Current liquid assets owned by the insuree and beneficiary. If 
excluded, defaults to 8. 


The inflation rate to be applied to the benefit amount and 
annual net take home pay. If excluded, defaults to 9. 


The inflation rate to be applied to all tuition. If excluded, defaults 
to 0. 


The tax rate to be applied to investment earnings from the 
interest rate. Life insurance benefits are assumed to be 


tax-free. If excluded, defaults to 0. 


A parameter to round the benefit amount up to a configurable 
number of digits. This parameter should be utilized if a firm will 
not underwrite exact life insurance amounts, but will round to 
the nearest amount. 0: round to the hundredth, 1: round to the 
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> 
a 
z 


margin_of_error 
float 


children_education_config 


map 


current_age 


integer, required 


education_config 


map, required 


start_age 


integer, required 


end_age 


integer, required 


total_annual_cost 


float, required 


income_config 


map 


annual net take home pay 


float, required 


percentage of income covered 


float 


income benefit duration 


integer 


beneficiary bequest config 


map 


bequest amount 


float, required 
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tenth, 2: round to a single digit, 3 : round to two digits, etc. If 
excluded, defaults to @. 


The margin of error to apply to the life insurance needed, before 
rounding. A margin of error of 0.10 would return 110% of 


the total insurance needed. If excluded, defaults to 0. 


Benefit information to provide for a child's primary, secondary 
and college education. 


The child's age as of the first period. 


A configuration of the child's education cost. 


The child's age at the beginning of the first education year. 


The child's age at the beginning of the last education year. 


The total annual cost of the child's education. 


Information on replacement income for beneficiaries. Income is 


assumed to increase with the rate of inflation. 


The policy owner's annual after-tax income. 


The percentage of annual net take home pay needed by 


beneficiaries. If excluded, defaults to 1. 


The number of years needed to provide replacement income to 
beneficiaries, starting at the first period. If excluded, defaults to 
10. 


Information on additional benefits needed by beneficiaries. 


The amount of the benefit, paid annually. 
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= Parameter 

> 

x 

zZ years_until_bequest 
integer 


bequest_duration 


integer 


client_id 


UUID, conditional requirement 


Example Response 


Hydrogen Proton API Reference 


Description 


The number of years until the benefit is needed. A value of 0 
indicates the benefit would be needed immediately (the first 
period). If excluded, defaults to @. 


The amount of years to repeat the benefit_amount . If 
excluded, defaults to 10. 


The ID of a Nucleus client used to derive one or more of the 
following based on the client's financials: mortgage balance, 
other debt,and liquid assets . If required parameters 
mortgage balance and/or other debt are not provided, 
client id is required. If a raw value for optional parameter 
liquid assets is not provided, we will use client id to try 
to derive this value instead. 


"life insurance needed": 390000, 


"total life insurance needed": 440000, 
"life insurance needs breakdown": { 
"mortgage": 200000, 
"other": 100000, 
"education": 213033.65, 
"income replacement": 243087.46, 
"beneficiary bequest": 47454.39, 
"end of life": 10000 
bo 
"return details": { 
"B: À 
"period earnings": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"cumulative withdrawals": 0, 
"ending balance": 840000 
bo 
"a": { 
"period earnings": 0, 
"period withdrawal": 361000, 
"cumulative earnings": 0, 
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"cumulative withdrawals": 361000, 
"ending balance": 479000 


NAV III 


Jo 

"am À 
"period_earnings": 21555, 
"period_withdrawal": 106524, 
"cumulative earnings": 21555, 
"cumulative withdrawals": 467524, 
"ending balance": 394031 

D 

"94 
"period earnings": 17731.39, 
"period withdrawal": 109977.48, 
"cumulative earnings": 39286.39, 
"cumulative withdrawals": 577501.48, 
"ending balance": 301784.91 

D 

"4": { 
"period earnings": 13580.32, 
"period withdrawal": 113566.18, 
"cumulative earnings": 52866.72, 
"cumulative withdrawals": 691067.66, 
"ending balance": 201799.06 

J 

"ors d 
"period_earnings": 9080.96, 
"period_withdrawal": 117296.11, 
"cumulative earnings": 61947.67, 
"cumulative withdrawals": 808363.77, 
"ending balance": 93583.9 

D 

"gri À 
"period earnings": 4211.28, 
"period withdrawal": 64865.45, 
"cumulative earnings": 66158.95, 
"cumulative withdrawals": 873229.22, 
"ending balance": 32929.73 


RESPONSE 
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Field 


NAV Ill 


life_insurance_needed 


total life insurance needed 


life insurance needs breakdown 


mortgage 


other 


education 


income replacement 


beneficiary bequest 


end of life 


return details 


period earnings 


period withdrawal 


cumulative earnings 


cumulative withdrawals 


Hydrogen Proton API Reference 


Description 


The supplemental life insurance needed by the user. 


The total life insurance needed by the user, including the current 
life insurance. 


A breakdown of what the life insurance proceeds will be used for. 


Insurance required to cover existing mortgage balance, paid 
immediately. 


Insurance required to cover other debt. 


Insurance required to cover future education expenses. 


Insurance required to cover loss of income. 


Insurance required to cover amount being bequested. 


Insurance required to cover end of life expenses. 


Portfolio return information over the length of the horizon, broken 
down by period. Period 0 represents the assets available 
including the calculated insurance payment. Period 1 reflects 
any immediate expenses, and the remaining balance is drawn 
down starting with period 2 to cover ongoing expenses. 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 
withdrawals are made. 

The withdrawal made for this period. 


The cumulative investment earnings made up to and including 
this period. 


The cumulative withdrawals made up to and including this period. 
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Field Description 


NAV Ill 


ending balance The ending balance, inclusive of earnings and contributions for 
the current period. 


NUCLEUS DATA DEPENDENCIES 


* Client 
* Aggregation Account 
« Aggregation Account Balance 


e Account Categories 


Major Purchase Calculator 


When planning to make a major purchase, such as a down payment on a home/car, investors need to 
determine how much is needed and how to stay on track. After collecting information about the user's major 
purchase, this tool solves for three different parameters: deposit amount, purchase amount, and purchase 
horizon. 


Deposit Amount 


A calculator to help determine the deposit amount needed to meet the major purchase goal. 


HTTP REQUEST 


POST /purchase calculator/deposit amount 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d 4 
"purchase horizon": 5, 
"purchase amount": 50000, 
"portfolio return": 0.06, 
"horizon frequency interval": "year", 
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"current savings": 0, 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/purchase calculator/depc 


Hydrogen Proton API Reference 


z "deposit_schedule": { 
= "deposit_frequency_interval": "year", 
"adjust deposit for inflation": true 
D 
"inflation rate": 0.02, 
"investment tax": 0.25 
ARGUMENTS 


Parameter 


purchase horizon 


integer, required 


purchase amount 


float, required 


portfolio return 
float, required 


horizon frequency interval 


string 


current savings 
float 


deposit schedule 


map 


deposit frequency interval 
string 


adjust deposit for inflation 


boolean 


inflation rate 
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Description 


The amount of time until the major purchase is made. 


The amount of the major purchase. 


The portfolio’s return, calculated on an annual basis. 


The interval at which to measure the purchase horizon. The 
value may be one of the following: year, quarter, month, or 
week . Earnings are calculated at the same frequency as 
horizon frequency interval. If excluded, defaults to year. 


The current amount of savings earmarked for the goal. If 
excluded, defaults to 9. 


The deposit schedule for the major purchase goal. 


The period interval to be used in relation to the 

deposit amount . The value may be one of the following: 
year, quarter, month, or week. If excluded, defaults to 
year. 


If true, the deposits are increased over time with the rate of 
inflation. If excluded, defaults to true. 


The annual inflation rate of the purchase amount . If excluded, 
defaults to 6 . 


8/3/23, 5:08 PM 


fffameter 


NAV Ill 


investment_tax 
float 


account_ids 
array[UUID] 


aggregation_account_ids 
array[UUID] 


Example Response 


"deposit amount": 12574.34, 


Hydrogen Proton API Reference 


Description 


The tax on the investments used to pay for the major purchase. 


If excluded, defaults to 0. 


The ID(s) of the Nucleus account(s) used to derive 

current savings. |f current savings is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
current savings.lf current savings is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


"deposit frequency interval": "year", 
"adjusted goal amount": 73605.39, 
"projected savings at purchase horizon": 73605.39, 


"total earnings": 8168.03, 


"total contributions": 65437.36, 


"return details": { 
"o": { 
"period earnings": 0, 


"period contribution": 0, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 


"ending balance": 9 


J 

"a": { 
"period earnings": 0, 
"period contribution": 12574.34, 
"cumulative earnings": 0, 
"cumulative contributions": 12574.34, 
"ending balance": 12574.34 

J 

AUS À 


"period earnings": 754.46, 


"period contribution": 12825.82, 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


165/440 


8/3/23, 5:08 PM 

"cumulative earnings": 754 
"cumulative contributions" 
"ending balance": 26154.62 


NAV Ill 


D 
"Se À 


"period earnings": 1569.28 


Hydrogen Proton API Reference 


.46, 
: 25400.16, 


3 


"period contribution": 13082.34, 
"cumulative earnings": 2323.74, 


"cumulative contributions" 
"ending balance": 40806.24 
D 
"4": d 
"period earnings": 2448.37 


: 38482.5, 


3 


"period contribution": 13343.99, 


"cumulative earnings": 4772.11, 


"cumulative contributions" 
"ending balance": 56598.6 
bo 
TB: À 
"period earnings": 3395.92 


: 51826.49, 


A 


"period contribution": 13610.87, 


"cumulative earnings": 8168.03, 


"cumulative contributions": 


"ending balance": 73605.39 


RESPONSE 


Field 


deposit amount 


deposit frequency interval 


adjusted goal amount 


projected savings at purchase horizon 
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Description 


The amount to deposit in order to meet the purchase 
goal. 


The frequency interval of the deposit. 


The effective goal target amount, adjusted for taxes and 


inflation. 


The total amount of savings that are projected to be 
available at the final horizon, expressed in today’s 
dollars. 
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Field 


NAV Ill 


total_earnings 


total contributions 


return details 


period earnings 


period contribution 


cumulative earnings 


cumulative contributions 


ending balance 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

e Portfolio Asset Size 
* Aggregation Account 


* Aggregation Account Balance 


Purchase Amount 


A calculator to help determine the amount that the user could afford for the major purchase, given the other 


inputs. 


HTTP REQUEST 


POST /purchase calculator/amount 
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Description 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


Portfolio return information over the length of the 
horizon, broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 
contributions are made. 


The deposit made for this period. 


The cumulative investment earnings made up to and 


including this period. 


The cumulative deposits made up to and including this 
period. 


The ending balance, inclusive of earnings and 
contributions for the current period. 
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a Example Request 
2 
curl -X POST -H "Authorization: Bearer «access token5" \ 
-H "Content-Type: application/json" N 
-d '{ 

"purchase_horizon": 6, 

"portfolio_return": 0.06, 

"horizon frequency interval": "year", 

"current savings": 0, 

"deposit schedule": ( 
"deposit amount": 10000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 

bo 

"inflation rate": 0.01, 

"investment tax": 0.2 

}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/purchase calculator/amor 
d > 
ARGUMENTS 
Parameter Description 
purchase_horizon The amount of time until the major purchase is made. 


integer, required 


portfolio_return The portfolio's return, calculated on an annual basis. 
float, required 


horizon frequency interval The interval at which to measure the purchase horizon.The 
string value may be one of the following: year, quarter, month, or 
week . Earnings are calculated at the same frequency as 


horizon frequency interval. If excluded, defaults to year. 


current savings The current amount of savings earmarked for the goal. If 

float excluded, defaults to 0. 

deposit schedule The deposit schedule for the major purchase goal. 

map 
deposit amount The periodic additions to the major purchase goal. If excluded, 
float defaults to 0. 
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Parameter 


deposit_frequency_interval 
string 


adjust_deposit_for_inflation 


boolean 


inflation_rate 
float 


investment_tax 
float 


account_ids 
array[UUID] 


aggregation_account_ids 
array[UUID] 


Example Response 


"purchase amount": 57119.83, 


Hydrogen Proton API Reference 


Description 


The period interval to be used in relation to the 
deposit amount. The value may be one of the following: 
year, quarter, month, or week. If excluded, defaults to 


year. 


If true, the deposits are increased over time with the rate of 
inflation. If excluded, defaults to true. 


The annual inflation rate of the purchase amount . If excluded, 
defaults to 6 . 


The tax on the investments used to pay for the major purchase. 
If excluded, defaults to ®. 


The ID(s) of the Nucleus account(s) used to derive 

current savings.lf current savings is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead 


The ID(s) of the Nucleus aggregation account(s) used to derive 
current savings.lf current savings is not provided, we 
will try to use account ids and/or 


aggregation account ids to derive this value instead 


"purchase amount adjusted": 53809.47, 


"projected savings at purchase horizon": 71399.79, 


"total earnings": 9879.64, 


"total contributions": 61520.15, 


"return details": { 
"o": f 


"period earnings": 0, 


"period contribution": 0, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 


"ending balance": 0 


D 


169/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 
n" 1 n" a { 
"period earnings": 0, 


NAV III 


"period contribution": 10000, 
"cumulative earnings": 0, 
"cumulative contributions": 10000, 
"ending balance": 10000 

bo 

"2": { 
"period earnings": 600, 
"period contribution": 10100, 
"cumulative earnings": 600, 
"cumulative contributions": 20100, 
"ending balance": 20700 

D 

"S sq 
"period earnings": 1242, 
"period contribution": 10201, 
"cumulative earnings": 1842, 
"cumulative contributions": 30301, 
"ending balance": 32143 

D 

"4": d 
"period earnings": 1928.58, 
"period contribution": 10303.01, 
"cumulative earnings": 3770.58, 
"cumulative contributions": 40604.01, 
"ending balance": 44374.59 

D 

TEE A 
"period earnings": 2662.48, 
"period contribution": 10406.04, 
"cumulative earnings": 6433.06, 
"cumulative contributions": 51010.05, 
"ending balance": 57443.11 

D 

"6": { 
"period earnings": 3446.59, 
"period contribution": 10510.1, 
"cumulative earnings": 9879.64, 
"cumulative contributions": 61520.15, 
"ending balance": 71399.79 
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Field 


NAV Ill 


purchase_amount 


purchase_amount_adjusted 


projected_savings at_purchase 


horizon 


total_earnings 


total_contributions 


return_details 


period earnings 


period contribution 


cumulative earnings 


cumulative contributions 


ending balance 


NUCLEUS DATA DEPENDENCIES 


* Account 

e Portfolio 

* Portfolio Asset Size 

* Aggregation Account 

e Aggregation Account Balance 


Purchase Horizon 


Hydrogen Proton API Reference 


Description 


The amount of the major purchase. 


The amount of the major purchase, represented in today's 
dollars. 


The total amount of savings that are projected to be available 
at purchase horizon, expressed in today's dollars. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


Portfolio return information over the length of the horizon, 
broken down by period. 


The earnings for this period. Earnings are calculated at the 


beginning of each period, before contributions are made. 


The deposit made for this period. 


The cumulative earnings made up to and including this period. 


The cumulative deposits made up to and including this period. 


The ending balance, inclusive of earnings and contributions for 
the current period. 


A calculator to help determine the amount of years needed to save for a major purchase. 
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HTTP REQUEST 


z POST /purchase_calculator/horizon 
2 
Example Request 
curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '( 
"purchase amount": 50000, 
"portfolio return": 0.06, 
"current savings": 0, 
"deposit schedule": ( 
"deposit amount": 10000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
D 
"inflation rate": 0.02, 
"investment tax": 0.25 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/purchase calculator/hori 
4 > 
ARGUMENTS 
Parameter Description 
purchase amount The amount of the major purchase. 


float, required 


portfolio return The portfolio's return, calculated on an annual basis. 
float, required 


current savings The current amount of savings earmarked for the goal. If 
float excluded, defaults to @. 
deposit schedule The deposit schedule for the major purchase goal. 
map 
deposit amount The periodic additions to the major purchase goal. If excluded, 
float defaults to 0. 
deposit frequency interval The period interval to be used in relation to the 
string deposit amount . The value may be one of the following: 
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Parameter 


adjust_deposit_for_inflation 


boolean 


inflation_rate 
float 


investment_tax 
float 


account_ids 
array[UUID] 


aggregation_account_ids 
array[UUID] 


Example Response 


"purchase horizon": 7, 


Hydrogen Proton API Reference 


Description 


year, quarter, month, or week. If excluded, defaults to 


year. 


If true, the deposits are increased over time with the rate of 
inflation. If excluded, defaults to true. 


The annual inflation rate of the purchase amount . If excluded, 
defaults to 6 . 


The tax on the investments used to pay for the major purchase. 
If excluded, defaults to ®. 


The ID(s) of the Nucleus account(s) used to derive 

current savings. If current savings is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead 


The ID(s) of the Nucleus aggregation account(s) used to derive 
current savings.lf current savings is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead 


"purchase horizon frequency interval": "year", 
"adjusted goal amount": 76579.04, 
"projected savings at purchase horizon": 88736.15, 


"total earnings": 14393.31, 


"total contributions": 74342.83, 


"return details": { 
"o": f 


"period earnings": 0, 


"period contribution": 0, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 


"ending balance": 0 


D 
ke: 
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"period earnings": 0, 
"period contribution": 10000, 


NAV III 


"cumulative earnings": 0, 
"cumulative contributions": 10000, 
"ending balance": 10000 

D 

ars {f 
"period earnings": 600, 
"period contribution": 10200, 
"cumulative earnings": 600, 
"cumulative contributions": 20200, 
"ending balance": 20800 

D 

"Br: { 
"period earnings": 1248, 
"period contribution": 10404, 
"cumulative earnings": 1848, 
"cumulative contributions": 30604, 
"ending balance": 32452 

D 

"4": d 
"period earnings": 1947.12, 
"period contribution": 10612.08, 
"cumulative earnings": 3795.12, 
"cumulative contributions": 41216.08, 
"ending balance": 45011.2 

bo 

"5": d 
"period earnings": 2700.67, 
"period contribution": 10824.32, 
"cumulative earnings": 6495.79, 
"cumulative contributions": 52040.4, 
"ending balance": 58536.19 

J 

"pr: { 
"period earnings": 3512.17, 
"period contribution": 11040.81, 
"cumulative earnings": 10007.96, 
"cumulative contributions": 63081.21, 
"ending balance": 73089.17 

D 

"s À 
"period earnings": 4385.35, 
"period contribution": 11261.62, 
"cumulative earnings": 14393.31, 
"cumulative contributions": 74342.83, 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 174/440 


8/3/23, 5:08 PM 


a } 
= } 
} 
RESPONSE 
Field 


purchase_horizon 


purchase_horizon_frequency_interval 


adjusted_goal_amount 


projected_savings_at_purchase_horizon 


total_earnings 


total_contributions 


return_details 


period_earnings 


period_contribution 


cumulative_earnings 


cumulative_contributions 
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Description 


The number of periods needed in order to meet the 
major purchase goal. 


The unit of time associated with purchase_horizon. 
Will always be year. 


The effective goal target amount, adjusted for taxes and 
inflation. 


The total amount of savings that are projected to be 
available at the major purchase date, expressed in 
today’s dollars. 

The total earnings generated over the horizon. 


The total contributions added over the horizon. 


Portfolio return information over the length of the 
horizon, broken down by period. 


The earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions are 
made. 


The deposit made for this period. 


The cumulative earnings made up to and including this 


period. 


The cumulative deposits made up to and including this 
period. 
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Field Description 


NAV Ill 


ending balance The ending balance, inclusive of earnings and 
contributions for the current period. 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

e Portfolio Asset Size 
e Aggregation Account 


* Aggregation Account Balance 


Mortgage Calculator 


Many users face the question of how much a mortgage may cost when deciding to buy a property. This tool 
simplifies the parameters to five components: the mortgage interest rate, mortgage term, home price, down 
payment, and the periodic (monthly) payment. Of those five parameters, this mortgage calculator provides 
three different endpoints to solve for the following parameters: a periodic (monthly) payment, down payment 
and total home price. 


Down Payment 


This calculator helps a user solve for the down payment they will need to pay, given the other factors in their 
home purchase. 


HTTP REQUEST 


POST /mortgage calculator/down payment 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '( 
"home price": 100000, 
"periodic payment": 8000, 
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"interest rate": 0.04, 
"mortgage term": 6 
}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/mortgage calculator/dowr 


NAV Ill 


ARGUMENTS 


Parameter Description 


home_price The total cost of the home, including down payments but excluding transactional 
float, required costs of purchasing the home (e.g. insurance, legal fees, closing costs, etc.) 


periodic_payment The periodic monthly payment for the mortgage. 


float, required 


interest_rate The annualized interest rate charged on the balance of the mortgage. If excluded, 
float defaults to 0.0. 

mortgage term The length of time the mortgage will take place, as expressed in months. If 
integer excluded, defaults to 360. 


Example Response 


"down payment": 52545.22, 
"total payment": 48000, 
"total principal": 47454.78, 
"total interest": 545.22, 
"total home cost": 100545.22, 
"schedule": { 
"as À 
"Payment": 0, 
"Principal": 0, 
"Interest": 0, 
"Cumulative Payment": 0, 
"Cumulative Principal": 0, 
"Cumulative Interest": 0, 
"Balance": 47454.78 
J 
"irs d 
"Payment": 8000, 
"Principal": 7844.65, 
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"Interest": 155.35, 

"Cumulative Payment": 8000, 
"Cumulative Principal": 7844.65, 
"Cumulative Interest": 155.35, 
"Balance": 39610.13 


NAV III 


D 

"Se? 
"Payment": 8000, 
"Principal": 7870.33, 
"Interest": 129.67, 
"Cumulative Payment": 16000, 
"Cumulative Principal": 15714.97, 
"Cumulative Interest": 285.03, 
"Balance": 31739.81 

D 

SC SI 
"Payment": 8000, 
"Principal": 7896.09, 
"Interest": 103.91, 
"Cumulative Payment": 24000, 
"Cumulative Principal": 23611.06, 
"Cumulative Interest": 388.94, 
"Balance": 23843.71 

D 

"4": { 
"Payment": 8000, 
"Principal": 7921.94, 
"Interest": 78.06, 
"Cumulative Payment": 32000, 
"Cumulative Principal": 31533.01, 
"Cumulative Interest": 466.99, 
"Balance": 15921.77 

D 

"Bd 
"Payment": 8000, 
"Principal": 7947.88, 
"Interest": 52.12, 
"Cumulative Payment": 40000, 
"Cumulative Principal": 39480.88, 
"Cumulative Interest": 519.12, 
"Balance": 7973.9 

bo 

"6": { 


"Payment": 8000, 
"Principal": 7973.9, 
"Interest": 26.1, 
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"Balance": 


ny 


RESPONSE 


Field 


down_payment 


total payment 


total principal 


total interest 


total home cost 


schedule 


Payment 


Principal 


Interest 


Cumulative Payment 


Cumulative Principal 


Hydrogen Proton API Reference 


"Cumulative Payment": 48000, 
"Cumulative Principal": 47454.78, 
"Cumulative Interest": 545.22, 


Description 


The payment due upfront when buying a home, given the other inputs 
provided by the user. 


The total mortgage payments made over mortgage term. 


The total amount that went toward the mortgage principal. 


The total amount that went toward the mortgage interest. 


The total cost of the home, including down payment and all mortgage 


payments. This value is greater than home price when interest rate 


is greater than O. 


Details for the mortgage payment, broken down by period. 


The total payment made for this period, consisting of interest and 


principal. 


The principal payment made for this period. 


The interest payment made for this period. 


The cumulative total payment made up to and including this period. 


The cumulative principal payment made up to and including this period. 
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zi 
z 


Field Description 


Cumulative Interest The cumulative interest payment made up to and including this period. 


Balance The remaining mortgage balance at the end of the period. 


Home Price 


This calculator helps a user solve for the total home price they can afford, given the other factors related to 
their home purchase. 


HTTP REQUEST 


POST /mortgage calculator/home price 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"down payment": 50000, 
"periodic payment": 8000, 
"interest rate": 0.04, 
"mortgage term": 6 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/mortgage calculator/home 


ARGUMENTS 


Parameter Description 


down_payment The payment due upfront when buying a home. 
float, required 


periodic payment The periodic monthly payment for the mortgage. 
float, required 


interest rate The annualized interest rate charged on the balance of the mortgage. If excluded, 
defaults to 0.0. 
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=  Farameter Description 

> 

= 
mortgage_term The length of time the mortgage will take place, as expressed in months. If 
integer excluded, defaults to 360. 


Example Response 


"home_price": 97454.78, 

"total payment": 48000, 

"total principal": 47454.78, 

"total interest": 545.22, 

"total home cost": 98000, 

"schedule": { 

"a": { 

"Payment": 0, 
"Principal": 0, 
"Interest": 0, 
"Cumulative Payment": 0, 
"Cumulative Principal": 0, 
"Cumulative Interest": 0, 
"Balance": 47454.78 


D 

"aue d 
"Payment": 8000, 
"Principal": 7844.65, 
"Interest": 155.35, 
"Cumulative Payment": 8000, 
"Cumulative Principal": 7844.65, 
"Cumulative Interest": 155.35, 
"Balance": 39610.13 

D 

Sa À 
"Payment": 8000, 
"Principal": 7870.33, 
"Interest": 129.67, 
"Cumulative Payment": 16000, 
"Cumulative Principal": 15714.97, 
"Cumulative Interest": 285.03, 
"Balance": 31739.81 

bo 

eo d 


"Payment": 8000, 
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"Principal": 7896.09, 


z "Interest": 103.91, 
= "Cumulative_Payment": 24000, 

"Cumulative_Principal": 23611.06, 
"Cumulative_Interest": 388.94, 
"Balance": 23843.71 

bo 

"4": d 
"Payment": 8000, 
"Principal": 7921.94, 
"Interest": 78.06, 
"Cumulative Payment": 32000, 
"Cumulative Principal": 31533.01, 
"Cumulative Interest": 466.99, 
"Balance": 15921.77 

D 

"Se T 
"Payment": 8000, 
"Principal": 7947.88, 
"Interest": 52.12, 
"Cumulative Payment": 40000, 
"Cumulative Principal": 39480.88, 
"Cumulative Interest": 519.12, 
"Balance": 7973.9 

D 

"6": { 
"Payment": 8000, 
"Principal": 7973.9, 
"Interest": 26.1, 
"Cumulative Payment": 48000, 
"Cumulative Principal": 47454.78, 
"Cumulative Interest": 545.22, 
"Balance": 0 

} 

} 
} 
RESPONSE 
Field Description 
home_price The total cost of the home that can be afforded, given the other inputs 


provided by the user. 
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Field 


NAV Ill 


total_payment 
total_principal 
total_interest 


total home cost 


schedule 


Payment 


Principal 


Interest 


Cumulative Payment 


Cumulative Principal 


Cumulative Interest 


Balance 


Periodic Payment 


Hydrogen Proton API Reference 


Description 


The total mortgage payments made over mortgage term. 

The total amount that went toward the mortgage principal. 

The total amount that went toward the mortgage interest. 

The total cost of the home, including down payment and all mortgage 
payments. This value is greater than home price when interest rate 
is greater than O. 


Details for the mortgage payment, broken down by period. 


The total payment made for this period, consisting of interest and 


principal. 


The principal payment made for this period. 


The interest payment made for this period. 


The cumulative total payment made up to and including this period. 


The cumulative principal payment made up to and including this period. 


The cumulative interest payment made up to and including this period. 


The remaining mortgage balance at the end of the period. 


This calculator helps a user solve for the monthly mortgage payment, given the other factors in their home 


purchase. 


HTTP REQUEST 


POST /mortgage calculator/periodic payment 
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a Example Request 
z 
curl -X POST -H "Authorization: Bearer «access token»" ^ 
-H "Content-Type: application/json" \ 
-d '{ 
"home_price": 100000, 
"down payment": 50000, 
"interest rate": 0.04, 
"mortgage term": 6 
}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/mortgage calculator/peri 
4 > 
ARGUMENTS 
Parameter Description 
home_price The total cost of the home, including down payments but excluding transactional costs 
float, required of purchasing the home (e.g. insurance, legal fees, closing costs, etc.) 


down_payment The payment due upfront when buying a home. 
float, required 


interest_rate The annualized interest rate charged on the balance of the mortgage. If excluded, 
float defaults to 0.0. 


mortgage term The length of time the mortgage will take place, as expressed in months. If excluded, 
integer defaults to 360. 


Example Response 


"periodic payment": 8429.08, 
"total payment": 50574.46, 
"total principal": 50000, 
"total interest": 574.46, 
"total home cost": 100574.46, 
"schedule": { 
"a": d 
"Payment": 0, 
"Principal": 0, 
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D 
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"Interest": 0, 

"Cumulative Payment": 0, 
"Cumulative Principal": 0, 
"Cumulative Interest": 0, 
"Balance": 50000 


{ 
"Payment": 8429.08, 


"Principal": 8265.39, 
"Interest": 163.69, 

"Cumulative Payment": 8429.08, 
"Cumulative Principal": 8265.39, 
"Cumulative Interest": 163.69, 
"Balance": 41734.61 


{ 
"Payment": 8429.08, 


"Principal": 8292.45, 

"Interest": 136.63, 

"Cumulative Payment": 16858.15, 
"Cumulative Principal": 16557.84, 
"Cumulative Interest": 300.32, 
"Balance": 33442.16 


{ 
"Payment": 8429.08, 


"Principal": 8319.6, 

"Interest": 109.48, 

"Cumulative Payment": 25287.23, 
"Cumulative Principal": 24877.44, 
"Cumulative Interest": 409.8, 
"Balance": 25122.56 


{ 
"Payment": 8429.08, 


"Principal": 8346.83, 

"Interest": 82.24, 

"Cumulative Payment": 33716.31, 
"Cumulative Principal": 33224.27, 
"Cumulative Interest": 492.04, 
"Balance": 16775.73 


{ 
"Payment": 8429.08, 


"Principal": 8374.16, 
"Interest": 54.92, 
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"Cumulative Payment": 42145.39, 


a "Cumulative Principal": 41598.43, 
= "Cumulative_Interest": 546.96, 
"Balance": 8401.57 
bo 
W 6 W E { 
"Payment": 8429.08, 
"Principal": 8401.57, 
"Interest": 27.5, 
"Cumulative_Payment": 50574.46, 
"Cumulative Principal": 50000, 
"Cumulative Interest": 574.46, 
"Balance": @ 
} 
} 
} 
RESPONSE 
Field Description 
periodic payment The periodic monthly payment for the mortgage, given the other inputs 
provided by the user. 
total payment The total mortgage payments made over mortgage term. 
total principal The total amount that went toward the mortgage principal. 
total interest The total amount that went toward the mortgage interest. 
total home cost The total cost of the home, including down payment and all mortgage 
payments. This value is greater than home price when interest rate 
is greater than O. 
schedule Details for the mortgage payment, broken down by period. 
Payment The total payment made for this period, consisting of interest and 
principal. 
Principal The principal payment made for this period 
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Field 
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Interest 


Cumulative Payment 


Cumulative Principal 


Cumulative Interest 


Balance 


Retirement Calculator 


Hydrogen Proton API Reference 


Description 


The interest payment made for this period. 


The cumulative total payment made up to and including this period. 


The cumulative principal payment made up to and including this period. 


The cumulative interest payment made up to and including this period. 


The remaining mortgage balance at the end of the period. 


When planning for retirement, investors need to determine how much is needed and how to bridge any gaps 


in their financial plan. After collecting information about the user's financial situation and desired retirement 


lifestyle, this tool solves for three different parameters: deposit amount, retirement lifestyle, and retirement 


expenses. 


Deposit Amount 


A calculator to help plan for the deposit amount needed to retire comfortably. 


HTTP REQUEST 


POST /retirement calculator/deposit amount 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


-d '{ 
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"current age": 70, 
"death age": 78, 
"retirement expenses": 40000, 


NAV Ill 


"portfolio return": 0.06, 
"retirement age":75, 
"percent of expenses covered": 0.25, 
"retirement savings": 5000, 
"retirement income": 5000, 
"deposit schedule": { 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
Yo 
“inflation rate": 0.02, 
"retirement tax": 0.25 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/retirement calculator/de 


ARGUMENTS 
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Parameter 


current_age 


integer, required 
death_age 

integer, required 
retirement_expenses 


float, required 


portfolio_return 
float, required 


retirement_age 
integer 


percent_of_expenses_covered 


float 


retirement_savings 
float 


Description 


The user’s current age. This will be used when determining the 
amount of years to accumulate funds. 


The user’s death age. This age will be used when determining 
the amount of years that retirement_expenses will be 
needed. 


The desired annual living expenses or lifestyle in retirement. 


The portfolio’s annualized return. 


The age the user will retire. This is the age that the user will 
cease adding to their retirement assets and begin drawing down 
funds to meet retirement expenses . If excluded, defaults to 
65. 


The percentage of current expenses needed in retirement. If 
excluded, defaults to 0.70. 


The current amount of retirement savings. If excluded, defaults 
to 0. 
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Parameter 


retirement_income 
float 


deposit_schedule 


map 


deposit_frequency_interval 


string 


adjust deposit for inflation 


boolean 


inflation rate 
float 


retirement tax 


float 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Example Response 


"deposit amount": 2351.62, 


Hydrogen Proton API Reference 


Description 


The amount of an income stream that will be available in 
retirement, expressed in today's dollars. If excluded, defaults to 
e. 


The deposit schedule for the retirement goal. 


The frequency at which to make additions to 

retirement savings in the periods before retirement. The 
value may be one of the following: year, quarter, month, or 
week . If excluded, defaults to year. 


If true, the deposit amount will be increased by the 
inflation rate. If excluded, defaults to true. 


The annual inflation rate of retirement expenses . If 
excluded, defaults to 9. 


The tax on assets in retirement. This tax rate will be applied to 
the assets that are needed for retirement expenses . If 
excluded, defaults to @. 


The ID(s) of the Nucleus account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 


aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 
aggregation account ids to derive this value instead. 


"deposit frequency interval": "year", 


"projected savings at retirement": 20456.61, 


"total earnings": 5738.8, 
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"total contributions": 12237.92, 
"total withdrawals": 17232.54, 
"total taxes": 5744.18, 
"return details": { 
"gs À 
"period earnings": 0, 


NAV III 


"period contribution": 0, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 

D 

"a": { 
"period earnings": 300, 
"period contribution": 2351.62, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 2351.62, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 7651.62 

D 

"ala À 
"period earnings": 459.1, 
"period contribution": 2398.65, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 759.1, 
"cumulative contributions": 4750.27, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 10509.37 

bo 

Br 
"period earnings": 630.56, 
"period contribution": 2446.62, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 1389.66, 
"cumulative contributions": 7196.89, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
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"ending balance": 13586.55 

bo 

"4": { 
"period earnings": 815.19, 


NAV III 


"period contribution": 2495.56, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 2204.85, 
"cumulative contributions": 9692.45, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 16897.3 

D 

"5: d 
"period earnings": 1013.84, 
"period contribution": 2545.47, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 3218.69, 
"cumulative contributions": 12237.92, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 20456.61 

J 

"B s 
"period earnings": 1227.4, 
"period contribution": 0, 
"period withdrawal": -5630.81, 
"period taxes": -1876.94, 
"cumulative earnings": 4446.09, 
"cumulative contributions": 12237.92, 
"cumulative withdrawals": -5630.81, 
"cumulative taxes": -1876.94, 
"ending balance": 14176.26 

D 

"ës / 
"period earnings": 850.58, 
"period contribution": 0, 
"period withdrawal": -5743.43, 
"period taxes": -1914.48, 
"cumulative earnings": 5296.66, 
"cumulative contributions": 12237.92, 
"cumulative withdrawals": -11374.24, 
"cumulative taxes": -3791.41, 
"ending balance": 7368.93 


D 
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= "8": { 

a "period earnings": 442.14, 

= "period_contribution": ®, 
"period withdrawal": -5858.3, 
"period taxes": -1952.77, 
"cumulative earnings": 5738.8, 
"cumulative contributions": 12237.92, 
"cumulative withdrawals": -17232.54, 
"cumulative taxes": -5744.18, 
"ending balance": 9 

} 
} 
} 
RESPONSE 
Field Description 


deposit amount 


deposit frequency interval 


projected savings at retirement 


total earnings 


total contributions 


total withdrawals 


total taxes 


return details 


period earnings 
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The amount to deposit in order to meet the retirement goal. 


The frequency interval of the deposit. 


The total amount of savings projected to be available at 
retirement, expressed in today’s dollars. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 


decumulation_horizon. 


The total taxes paid on withdrawals over 


decumulation_horizon. 


Portfolio return information over the length of the horizon, 
broken down by period. 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 


withdrawals are made. 
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Field 


period contribution 


period withdrawal 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative taxes 


ending balance 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

* Portfolio Asset Size 

* Aggregation Account 

e Aggregation Account Balance 


Percent of Costs Covered 


Hydrogen Proton API Reference 


Description 


The deposit made for this period. 


The withdrawal made for this period. 


The taxes paid during this period. 


The cumulative investment earnings made up to and including 


this period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this 


period. 


The cumulative taxes paid up to and including this period. 


The ending balance, inclusive of earnings and contributions for 
the current period. 


A calculator to help determine the percentage of the retirement lifestyle that can be afforded. 


HTTP REQUEST 


POST /retirement calculator/percent covered 
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Example Request 


NAV Ill 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


-d ^f 
"current age": 50, 
"death age": 57, 
"retirement expenses": 40000, 
"portfolio return": 0.06, 
"retirement age": 55, 
"retirement savings": 5000, 
"retirement income": 5000, 
"deposit schedule": ( 
"deposit amount": 10000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
D 


"inflation rate": @.02, 
"retirement tax": 0.25 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/retirement calculator/pe 


« > 
ARGUMENTS 
Parameter Description 
current_age The user's current age. This will be used when determining the 
integer, required amount of years to accumulate funds. 
death age The user's death age. This age will be used when determining 
integer, required the amount of years that retirement expenses will be 
needed. 
retirement expenses The desired annual living expenses or lifestyle in retirement. 


float, required 


portfolio return The portfolio's annualized return. 


float, required 


retirement age The age the user will retire. This is the age that the user will 
integer cease adding to their retirement assets and begin drawing down 
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Parameter 


retirement_savings 
float 


retirement_income 
float 


deposit_schedule 
map 


deposit_amount 
float 


deposit_frequency_interval 


string 


adjust deposit for inflation 
boolean 


inflation rate 
float 


retirement tax 
float 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Hydrogen Proton API Reference 


Description 


funds to meet retirement expenses. If excluded, defaults to 
65. 


The current amount of retirement savings. If excluded, defaults 
to 0. 


The amount of an income stream that will be available in 
retirement, expressed in today's dollars. If excluded, defaults to 
e. 


The deposit schedule for the retirement goal. 


The periodic additions to retirement savings in the period before 
retirement. If excluded, defaults to 0 . 


The frequency at which to make additions to retirement savings 
in the periods before retirement. The value may be one of the 
following: year, quarter, month, or week. If excluded, 


defaults to year . 


If true, the deposit amount will be increased by the 
inflation rate. If excluded, defaults to true. 


The annual inflation rate of retirement expenses . If 


excluded, defaults to 8. 


The tax on assets in retirement. This tax rate will be applied to 
the assets that are needed for retirement expenses . If 
excluded, defaults to 8. 


The ID(s) of the Nucleus account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 


aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 
aggregation account ids to derive this value instead. 
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Example Response 


NAV III 


"achievable expenses": 23465.95, 
"target expenses": 35000, 
"percent of expenses covered": 0.6705, 
"projected savings at retirement": 65227.32, 
"total earnings": 14134.9, 
"total contributions": 52040.4, 
"total withdrawals": 53381.48, 
"total taxes": 17793.83, 
"return details": { 
"9": À 
"period earnings": 0, 
"period contribution": 0, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 
D 
Ute of 
"period earnings": 300, 
"period contribution": 10000, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 10000, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 15300 
D 
Vas À 
"period earnings": 918, 
"period contribution": 10200, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 1218, 
"cumulative contributions": 20200, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 26418 
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"period earnings": 1585.08, 


NAV III 


"period contribution": 10404, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 2803.08, 
"cumulative contributions": 30604, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 38407.08 

bo 

"4": { 
"period earnings": 2304.42, 
"period contribution": 10612.08, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 5107.5, 
"cumulative contributions": 41216.08, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 51323.58 

D 

GR 
"period earnings": 3079.42, 
"period contribution": 10824.32, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 8186.92, 
"cumulative contributions": 52040.4, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 65227.32 

J 

"B s T 
"period earnings": 3913.64, 
"period contribution": 0, 
"period withdrawal": -26426.47, 
"period taxes": -8808.82, 
"cumulative earnings": 12100.56, 
"cumulative contributions": 52040.4, 
"cumulative withdrawals": -26426.47, 
"cumulative taxes": -8808.82, 
"ending balance": 33905.66 


D 
"Z" € 
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“period withdrawal": 
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"period earnings": 2034.34, 
"period contribution": 0, 


-26955, 


"period taxes": -8985, 


"cumulative earnings": 14134.9, 


"cumulative contributions": 52040.4, 


"cumulative withdrawals": -53381.48, 
"cumulative taxes": -17793.83, 
"ending balance": @ 
} 
} 
} 
RESPONSE 
Field Description 


achievable expenses 


target expenses 


percent of expenses covered 


projected savings at retirement 


total earnings 


total contributions 


total withdrawals 


total taxes 


return details 


period earnings 
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The annual living expenses or lifestyle that can be covered in 
retirement, expressed in today’s dollars. 


The retirement_expenses input representing the target 
annual goal amount. 


The percentage of target_expenses that can be covered. 


The total amount of savings that are projected to be available at 
retirement, expressed in today’s dollars. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 
decumulation_horizon. 


The total taxes paid on withdrawals over 
decumulation_horizon. 


Portfolio return information over the length of the horizon, 
broken down by period. 


The investment earnings for this period. Earnings are calculated 
at the beginning of each period, before contributions or 
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Field 
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period contribution 


period withdrawal 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative taxes 


ending balance 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

e Portfolio Asset Size 

e Aggregation Account 

e Aggregation Account Balance 


Retirement Expenses 


Hydrogen Proton API Reference 


Description 


withdrawals are made. 


The deposit made for this period. 


The withdrawal made for this period. 


The taxes paid during this period. 


The cumulative investment earnings made up to and including 


this period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this 


period. 


The cumulative taxes paid up to and including this period. 


The ending balance, inclusive of earnings and contributions for 
the current period. 


A calculator to help plan for the amount of expenses that will be incurred in retirement. 


HTTP REQUEST 


POST /retirement calculator/expenses 
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Example Request 


NAV Ill 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


-d '{ 
"current_age": 50, 
"death age": 57, 
"portfolio return": 0.06, 
"retirement age": 55, 
"percent of expenses covered": 0.25, 
"retirement savings": 5000, 
"retirement income": 5000, 
"deposit schedule": ( 
"deposit amount": 10000, 
"deposit frequency interval": "year", 
"adjust deposit for inflation": true 
D 


"inflation rate": @.02, 
"retirement tax": 0.25 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/retirement calculator/e» 


« > 
ARGUMENTS 
Parameter Description 
current_age The user's current age. This will be used when determining the 
integer, required amount of years to accumulate funds. 
death age The user's death age. This age will be used when determining 
integer, required the amount of years that retirement expenses will be 
needed. 
portfolio return The portfolio's annualized return. 


float, required 


retirement age The age the user will retire. This is the age that the user will 

integer cease adding to their retirement assets and begin drawing down 
funds to meet retirement expenses . If excluded, defaults to 
654; 
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Parameter 


percent of expenses covered 
float 


retirement savings 
float 


retirement income 
float 
deposit schedule 


map 


deposit amount 
float 


deposit frequency interval 


string 


adjust deposit for inflation 


boolean 


inflation rate 
float 


retirement tax 


float 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Hydrogen Proton API Reference 


Description 


The percentage of current expenses needed in retirement. If 
excluded, defaults to 8.70. 


The current amount of retirement savings. If excluded, defaults 
to 0. 


The amount of an income stream that will be available in 
retirement, expressed in today's dollars. If excluded, defaults to 
8. 


The deposit schedule for the retirement goal. 


The periodic additions to retirement savings in the period before 
retirement. If excluded, defaults to 0 . 


The frequency at which to make additions to retirement savings 
in the periods before retirement. The value may be one of the 
following: year, quarter, month, or week. If excluded, 
defaults to year . 


If true, the deposit amount will be increased by the 
inflation rate. If excluded, defaults to true. 


The annual inflation rate of retirement expenses . If 
excluded, defaults to 8. 


The tax on assets in retirement. This tax rate will be applied to 
the assets that are needed for retirement expenses . If 
excluded, defaults to 9. 


The ID(s) of the Nucleus account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 
aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
retirement savings.lf retirement savings is not 
provided, we will try to use account ids and/or 


aggregation account ids to derive this value instead. 
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Example Response 


NAV III 


"projected retirement expenses": 111336.69, 
"projected retirement expenses adjusted": 98863.8, 
"projected savings at retirement": 65227.32, 
"total earnings": 14134.9, 
"total contributions": 52040.4, 
"total withdrawals": 53381.48, 
"total taxes": 17793.83, 
"return details": { 
"a": { 
"period earnings": 0, 
"period contribution": 0, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 0, 
"cumulative contributions": 0, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 5000 
D 
le i 
"period earnings": 300, 
"period contribution": 10000, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 300, 
"cumulative contributions": 10000, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 15300 
bo 
"da À 
"period earnings": 918, 
"period contribution": 10200, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 1218, 
"cumulative contributions": 20200, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 26418 


D 
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"period earnings": 1585.08, 


NAV III 


"period contribution": 10404, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 2803.08, 
"cumulative contributions": 30604, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 38407.08 

D 

"4": d 
"period earnings": 2304.42, 
"period contribution": 10612.08, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 5107.5, 
"cumulative contributions": 41216.08, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 51323.58 

bo 

"5": 1 
"period earnings": 3079.42, 
"period contribution": 10824.32, 
"period withdrawal": 0, 
"period taxes": 0, 
"cumulative earnings": 8186.92, 
"cumulative contributions": 52040.4, 
"cumulative withdrawals": 0, 
"cumulative taxes": 0, 
"ending balance": 65227.32 

D 

"6": { 
"period earnings": 3913.64, 
"period contribution": 0, 
"period withdrawal": -26426.47, 
"period taxes": -8808.82, 
"cumulative earnings": 12100.56, 
"cumulative contributions": 52040.4, 
"cumulative withdrawals": -26426.47, 
"cumulative taxes": -8808.82, 
"ending balance": 33905.66 

J 

"T: d 
"period earnings": 2034.34, 
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"period taxes": -8985, 


"period contribution": 0, 
"period withdrawal": -26955, 


Hydrogen Proton API Reference 


"cumulative earnings": 14134.9, 


"cumulative contributions": 52040.4, 
"cumulative withdrawals": -53381.48, 


"cumulative taxes": -17793.83, 
"ending balance": 9 
} 
} 
} 
RESPONSE 
Field 


projected retirement expenses 


projected retirement expenses adjusted 


projected savings at retirement 


total earnings 


total contributions 


total withdrawals 


total taxes 


return details 


period earnings 
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Description 


The after-tax annual living expenses or lifestyle 


available in retirement. 


The after-tax annual living expenses or lifestyle 
available in retirement, expressed in today’s dollars. 


The total amount of savings that are projected to be 
available at retirement, expressed in today’s dollars. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of withdrawals taken over 


decumulation_horizon. 


The total taxes paid on withdrawals over 


decumulation_horizon. 


Portfolio return information over the length of the 
horizon, broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 


contributions or withdrawals are made. 
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Field 


period contribution 


period withdrawal 


period taxes 


cumulative earnings 


cumulative contributions 


cumulative withdrawals 


cumulative taxes 


ending balance 


NUCLEUS DATA DEPENDENCIES 


e Account 

e Portfolio 

* Portfolio Asset Size 

* Aggregation Account 

* Aggregation Account Balance 


Savings Calculator 


Hydrogen Proton API Reference 


Description 


The deposit made for this period. 


The withdrawal made for this period. 


The taxes paid during this period. 


The cumulative investment earnings made up to and 


including this period. 


The cumulative deposits made up to and including this 
period. 


The cumulative withdrawals made up to and including 
this period. 


The cumulative taxes paid up to and including this 
period. 


The ending balance, inclusive of earnings and 
contributions for the current period. 


While more detail is usually welcomed by financial professionals, some firms opt to provide simple calculators 


for simple savings or investing products. This endpoint provides a calculator that can show a simple growth of 


investment over time. After providing return, deposit, and balance information, the calculator returns an ending 
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balance and simulation details. Earnings are calculated at the beginning of each period, before deposits for 


a that period are considered. Tax rates, if provided, are applied in the return calculation. Returns are calculated 
7 atthe same frequency stipulated in horizon frequency interval. 
HTTP REQUEST 
POST /savings calculator 
Example Request 
curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"initial balance": 10000, 
"horizon": 5, 
"return schedule": [0.02, 0.025, 0.025, 0.025, 0.03], 
"horizon frequency interval": "year", 
"deposit schedule": 
[ 
{ 
"deposit amount": 100, 
"deposit frequency interval": "month", 
"deposit duration": 120, 
"adjust deposit for inflation": true 
J 
{ 
"deposit amount": 2000, 
"deposit frequency interval": "year", 
"deposit duration": 10, 
"adjust deposit for inflation": true 
} 
L 
"tax rate": 0.33, 
"inflation rate": 0.02 
)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/savings calculator" 
ARGUMENTS 
Parameter Description 
horizon The number of time periods in the savings horizon, where each 
integer, required period represents horizon frequency interval. 
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Parameter 


return_schedule 


array, required 


horizon_frequency_interval 


string 


initial balance 
float 


deposit schedule 


array[map] 


deposit amount 
float 


deposit frequency interval 
string 
deposit duration 


string 


adjust deposit for inflation 


boolean 


tax rate 
float 


inflation rate 
float 


account ids 
array[UUID] 


aggregation account ids 
array[UUID] 


Hydrogen Proton API Reference 


Description 


The rate of return per period. Providing an array of length 1, 
such as [0.04], will apply the value to each period in horizon. 


The frequency interval for horizon. Must be one of year, 
quarter, month, week, or day. Defaults to year. 


The initial balance of the investment. Defaults to 0. 


Details on the deposit plan. If excluded, no deposits are 
included in the calculation. 


The amount deposited in a given period and frequency. If 
excluded, defaults to @. 


The period interval to be used in relation to 
deposit duration. Must be one of year, quarter, month, 


week , or day . Defaults to year . 


The amount of intervals for the time period. If excluded, defaults 
to the number of intervals given in horizon. 


If true, adjusts the deposit using the inflation rate . If 
excluded, defaults to true. 


The tax rate to be applied to investment earnings. If excluded, 
defaults to @. 


The inflation rate to be applied to deposits. If excluded, defaults 
to 0. 


The ID(s) of the Nucleus account(s) used to derive 

initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 


The ID(s) of the Nucleus aggregation account(s) used to derive 
initial balance. If initial balance is not provided, we 
will try to use account ids and/or 

aggregation account ids to derive this value instead. 
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> 
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zZ create_log 
boolean 


Example Response 


"ending_balance": 28465.18, 
"return_details": { 
"o": { 


Hydrogen Proton API Reference 


Description 


If true, a record of this Proton request URL, request body, 
response body, and Nucleus UUID(s), where applicable, will be 
stored in Electron as an audit log, and the resulting 

audit log id will be returned in the Proton response. 
Defaults to false. 


"period earnings": 0, 


"period contribution": 0, 


"period withdrawal": 
"cumulative earnings 


e, 


": ©, 


"cumulative contributions": 0, 


"cumulative withdrawals": 0, 
"ending balance": 10000 


J 
"1": { 


"period earnings": 134, 


"period contribution": 3264, 


"period withdrawal": 


e, 


"cumulative earnings": 134, 


"cumulative contributions": 3264, 


"cumulative withdrawals": 0, 


"ending balance": 13398 


D 
EE 


"period earnings": 224.42, 


"period contribution": 3329.28, 


"period withdrawal": 


e, 


"cumulative earnings": 358.42, 


"cumulative contributions": 6593.28, 


"cumulative withdrawals": 0, 
"ending balance": 16951.7 


D 
tubes A 


"period earnings": 283.94, 
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"period contribution": 3395.87, 
"period withdrawal": 0, 


NAV Ill 


"cumulative earnings": 642.36, 
"cumulative contributions": 9989.15, 
"cumulative withdrawals": 0, 

"ending balance": 20631.5 


J 
"a": d 
"period earnings": 345.58, 
"period contribution": 3463.78, 
"period withdrawal": 0, 
"cumulative earnings": 987.94, 
"cumulative contributions": 13452.93, 
"cumulative withdrawals": 0, 
"ending balance": 24440.86 
bo 
"gms f 
"period earnings": 491.26, 
"period contribution": 3533.06, 
"period withdrawal": 0, 
"cumulative earnings": 1479.2, 
"cumulative contributions": 16985.99, 
"cumulative withdrawals": 0, 
"ending balance": 28465.18 
} 
} 
} 
RESPONSE 
Field Description 
ending_balance The ending balance of the investment, represented in today's dollars. 
return details Portfolio return information over the length of the horizon, broken down by 
period. 
period earnings The investment earnings for this period. Earnings are calculated at the 


beginning of each period, before contributions or withdrawals are made. 


period contribution The deposit made for this period. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 209/440 


8/3/23, 5:08 PM Hydrogen Proton API Reference 
Field Description 


> 
E 
zZ period_withdrawal The withdrawal made for this period. 


cumulative_earnings The cumulative investment earnings made up to and including this period. 


ending_balance The ending balance, inclusive of earnings and contributions for the current 
period. 
audit_log_id The unique id of the audit log record created in Electron. Only returned 


when create_log = true. 


NUCLEUS DATA DEPENDENCIES 


* Account 

* Portfolio 

e Portfolio Asset Size 

* Aggregation Account 

* Aggregation Account Balance 


Variable Annuity 


When planning for retirement or other financial outcomes, this service projects a variable annuity plan that is 
tied to a group of underlying investments. The Monte Carlo-based projection can help to evaluate potential 
annuity results and get a better understanding of how a variable annuity product may behave through both the 
accumulation phase and the payout phase. 


HTTP REQUEST 


POST /variable annuity 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
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}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/variable annuity" 


ARGUMENTS 


Hydrogen Proton API Reference 


"portfolio tickers": [ 
"HD"; 
"CVX", 
"JNJ" 
]; 
"portfolio weights": [ 
0.3, 
0.3, 
8.4 
]; 
"accumulation horizon": 4, 
"decumulation horizon": 3, 
"initial balance": 25000, 
"frequency interval": "year", 
"deposit schedule": ( 
"deposit amount": 1000 5 


"deposit frequency interval": "year", 


"adjust deposit for inflation" 


D 
"inflation rate": 0.01, 
"tax rate": 0.2, 
"annuitization rate": 0.05, 
"guaranteed rate benefit": [ 
{ 
“start”: 1; 
"end": 7, 
"min rate": 0.0, 
"max rate": 0.15 


Jo 


"guaranteed accumulation benefit 
"n": 1000, 

"result type": "median", 

"p^ s 50; 

"remove outliers": true, 

"start date": "2016-01-01", 

"end date": "2018-01-01", 
"trading days per year": 252, 


"use proxy data": false 
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Parameter 


portfolio tickers 


array, conditional requirement 


portfolio weights 


array, conditional requirement 


accumulation_horizon 


integer, required 


decumulation_horizon 


integer, required 
frequency interval 
string 

initial balance 


float 


deposit schedule 


map 


deposit amount 
float 


deposit frequency interval 


string 


adjust deposit for inflation 


boolean 


inflation rate 
float 


tax rate 
float 


annuitization rate 
float 


guaranteed rate benefit 
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Description 


Portfolio tickers, referencing securities defined in the Nucleus 
API. 


Portfolio weights, corresponding to portfolio tickers . Must 
sum to 1.0. Must be the same length as portfolio tickers. 


The number of time periods until the payout phase begins. 


The number of time periods in the payout or decumulation 


phase. 


Unit of time associated with accumulation horizon, 


decumulation horizon, start, end, and annuity payments. 


Value may be one of: year, quarter, month, week, day. 


The starting balance in the annuity plan, prior to any ongoing 
contributions. Defaults to @. 


The schedule of ongoing deposits to be made during the 
accumulation horizon. Includes the fields shown below. 


The periodic value of the deposit. Must be greater than or equal 
to 0. Defaults to @. 


The period interval to be used in relation to deposit_amount. 
Must be one of year, quarter, month, week, or day. 
Defaults to year. 


If true, deposit_amount will be adjusted over time based on 
inflation_rate. Defaults to true. 


The annualized rate of inflation. Defaults to @. 


The tax rate applied to annuity payouts. Defaults to @. 


The discount rate used to calculate annuity payout amounts 
during decumulation horizon. Defaults to 8. 


Boundaries enforced on the plan’s rate of return. Each 
underlying map includes the fields below. 
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Easgmeter 
start 


integer 


end 


integer 


min rate 
float 


max_rate 
float 


guaranteed accumulation benefit 
float 


n 


integer 
result type 
string 


float 


remove outliers 


boolean 
start date 
date 


end date 
date 


trading days per year 


integer 
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Description 


The starting period for the guarantee, where 1 indicates the 


first period in accumulation horizon. Must be greater than or 


equal to 1. Defaults to 1. 


The ending period for the guarantee. Must be less than or equal 
to the sum of accumulation horizon and 
decumulation horizon. Defaults to the sum of 


accumulation horizon and decumulation horizon. 


The minimum allowable rate. Must be less than or equal to 


max rate. 


The maximum allowable rate. Must be greater than or equal to 


min rate. 


A guaranteed lower bound for the plan balance at the end of 


accumulation horizon. 


The number of Monte Carlo simulations to run. Defaults to 
1000. 


The type of Monte Carlo result to consider. Must be one of 


mean, median,or custom. Defaults to median. 


A Monte Carlo result percentile to consider, applicable when 
result type is custom. Must be between 0 and 100 
inclusive. Defaults to 50. 


If true , remove outlying results. If true , outlier analysis is 
performed on a median absolute deviation (MAD) basis, at the 
2.5 threshold. Defaults to false. 


Start date used for ticker price history. Defaults to the earliest 


common date among portfolio tickers prices. 


End date used for ticker price history. Defaults to the latest 
common date among portfolio tickers prices. 


The number of days per year for which a portfolio is subject to 
market fluctuation. Defaults to 252 . 
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Parameter 


use proxy data 
boolean 


market data source 


string 


account id 


UUID, conditional requirement 


aggregation account id 


UUID, conditional requirement 


allocation id 


UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


If true, incorporate proxy price data as defined at the Security 
level in the Nucleus API. Proxy data is merged with base 
security data to form a continuous price history. Defaults to 
false. 


Source of security price data to be used in the analysis. Value 
may be nucleus or integration. When value is nucleus, 
security price data is sourced from Nucleus Security Price. 
When value is integration , security price data is sourced 
from a configured Integration Market Data vendor. Defaults to 
nucleus. 


The ID of a Nucleus account used to derive 

portfolio tickers and portfolio weights . If 
portfolio tickers or portfolio weights is not provided, 
one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 
portfolio tickers and portfolio weights . If 
portfolio tickers or portfolio weights is not provided, 
one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus allocation used to derive 

portfolio tickers and portfolio weights . If 
portfolio tickers or portfolio weights is not provided, 
one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers 
and portfolio weights.lf portfolio tickers or 
portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 
portfolio id is required. 


The ID of a Nucleus portfolio used to derive 

portfolio tickers and portfolio weights. If 
portfolio tickers or portfolio weights is not provided, 
one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 
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st 

zZ create_log 
boolean 


Example Response 


Hydrogen Proton API Reference 


Description 


If true, a record of this Proton request URL, request body, 
response body, and Nucleus UUID(s), where applicable, will be 
stored in Electron as an audit log, and the resulting 

audit log id will be returned in the Proton response. 
Defaults to false. 


"accumulation balance": 46331.26, 


"total earnings": 29635.08, 


"total contributions": 4101.01, 
"total withdrawals": 46988.87, 


"total taxes": 11747.22, 
"return details": { 
"o": { 


"period earnings": 0, 


"period contribution": 0, 


"period withdrawal": 
"period tax": 0, 


e, 


"cumulative earnings": 0, 


"cumulative contributions": 0, 


"cumulative withdrawals": 0, 


"cumulative tax": 0, 


"ending balance": 25000 


D 
Art 


"period earnings": 3750, 


"period contribution": 1010, 


"period withdrawal": 
"period tax": 0, 


e, 


"cumulative earnings": 3750, 


"cumulative contributions": 1010, 


"cumulative withdrawals": 0, 


"cumulative tax": 0, 


"ending balance": 29760 


D 
"2": { 


"period earnings": 4244.4, 


"period contribution": 1020.1, 
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"period withdrawal": 0, 
"period tax": 0, 


NAV III 


"cumulative earnings": 7994.4, 
"cumulative contributions": 2030.1, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 35024.5 

bo 

Tet À 
"period earnings": 4120.74, 
"period contribution": 1030.3, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 12115.14, 
"cumulative contributions": 3060.4, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 40175. 54 

D 

"4": { 
"period earnings": 5115.12, 
"period contribution": 1040.6, 
"period withdrawal": 0, 
"period tax": 0, 
"cumulative earnings": 17230.26, 
"cumulative contributions": 4101.01, 
"cumulative withdrawals": 0, 
"cumulative tax": 0, 
"ending balance": 46331.26 

D 

"5": ( 
"period earnings": 5696.16, 
"period contribution": 0, 
"period withdrawal": 14556.13, 
"period tax": 3639.03, 
"cumulative earnings": 22926.42, 
"cumulative contributions": 4101.01, 
"cumulative withdrawals": 14556.13, 
"cumulative tax": 3639.03, 
"ending balance": 33832.27 

D 

"6": { 
"period earnings": 4395.9, 
"period contribution": 0, 
"period withdrawal": 15664.22, 
"period tax": 3916.06, 
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"cumulative tax" 
"ending balance" 


D 
Gah 
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"cumulative earnings": 27322.31, 
"cumulative contributions": 4101.01, 
"cumulative withdrawals": 30220.35, 
: 7555.09, 

: 18647.88 


"period earnings": 2312.76, 


"period contribution": 0, 
"period withdrawal": 16768.52, 
"period tax": 4192.13, 
"cumulative earnings": 29635.08, 


"cumulative contributions": 4101.01, 
"cumulative withdrawals": 46988.87, 


"cumulative tax": 


"ending balance" 


RESPONSE 


Field 


accumulation balance 


total earnings 


total contributions 


total withdrawals 


total taxes 


return details 


period earnings 


11747.22, 


: 0 


Description 


The balance at the end of accumulation horizon, before annuity 


payments occur. 


The total earnings generated over the horizon. 


The total contributions added over the horizon. 


The total amount of annuity payments over 


decumulation horizon. 


The total taxes paid on annuity payments over 
decumulation horizon. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions are made. 
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> 
< 
zZ period_contribution 


period_withdrawal 
period_tax 
cumulative_earnings 
cumulative_contributions 
cumulative_withdrawals 
cumulative_tax 
ending_balance 


audit_log_id 


NUCLEUS DATA DEPENDENCIES 


e Security 

e Security Price 

* Account 

* Portfolio 

e Portfolio Holding 

* Model 

e Model Holding 

* Allocation 

* Allocation Composition 
* Aggregation Account 


e Aggregation Account Holding 


Hydrogen Proton API Reference 


Description 


The deposit made for this period. 


The withdrawal made for this period. 


The tax amount for this period. 


The cumulative investment earnings made up to and including this 


period. 


The cumulative deposits made up to and including this period. 


The cumulative withdrawals made up to and including this period. 


The cumulative taxes up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 


current period. 


The unique id of the audit log record created in Electron. Only 


returned when create log = true. 
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TO 
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Only one of account id, aggregation account id, allocation id, model id,and portfolio id 


should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Goals 


Accumulation Goal Allocation 


This service offers a framework to match an accumulation goal to an appropriate portfolio, with the ability to 


prioritize an investor's risk appetite or prioritize the goal achievement. Allocations are selected from a universe 
based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated 


portfolios. This framework also has built-in support for a goal recommendation engine, which recommends 


actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved 


in the initially presented allocation context. 


HTTP REQUEST 


Example Request 


POST /goal accumulation/allocation 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
dir 

"allocation method": "create", 

"allocation priority": "goal", 

"allocations": [ 
"406ec16e-ebae-4130-a6c0-1cacb72569a2", 
"740f6466-3300-4122-927d-4a691359fa32", 
"0a02058f -4046-48de-b3d2-aeefd6d4efac" 


L 
"opt config": { 


"tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", 


"min assets": 6, 

"w config": { 
"w min major": 0.05, 
"w max major": 1, 
"w min minor": 0.05, 
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"w max minor": @.1, 
"cash amount": 0.0 


NAV III 


bo 
"w asset config": { 
"US Equities": 1.0, 
"Fixed Income": 1.0, 
"Intl Equities": 1.0, 
"EM Equities": 1.0, 
"Commodities": 1.0 
Jo 
"sec types": ["minor", "major", "minor", "minor", "minor", "minor"], 
"start date": "2016-01-01", 
"end date": "2017-01-01" 
bo 
"risk score": 77, 
"trading days per year": 252, 
"horizon": 5, 
"horizon frequency": "year", 
"deposit config": [ 
{ 
"dep start reference": "a start", 
"dep start period": 0, 
"dep end reference": "a start", 
"dep end period": 3, 
"dep amount": 2000, 
"dep frequency": "year", 
"dep inflation": 0.0 


L 
"goal config": { 
"goal amount": 25000, 
"goal inflation": 0.0 
J 
"recommendation_config": { 
"recommend": true, 
"inv min": 0, 
"inv max": 1000, 
"dep min": 0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 
bo 
"curr inv": 10000, 
"recommend type": "recurring", 
"conf tgt": 0.9, 
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)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/goal accumulation/alloce 


= "n": 1000, 

a "remove outliers": true, 

= "thresh_type": "perc", 
"thresh": ®, 
"withdrawal tax": 0.0, 
"adjust for compounding": false, 
"compounding rate": 0.0, 
"use proxy data": false 

ARGUMENTS 


Parameter 


allocation method 


string, required 


allocation priority 


string, required 


opt config 
map, conditional requirement 


tickers 


array, required 


min assets 


integer, required 


w config 


map, required 


Description 


The allocation universe source, may be either create or select. 
create constructs an allocation universe from a dynamically generated 
efficient frontier, based on opt config. select derives an allocation 
universe from pre-defined allocations, as stipulated by allocations. 


The priority to consider when deriving the appropriate allocation, may be 
risk or goal. risk finds a portfolio that corresponds to an investor's 
risk score within the universe of potential portfolios. goal does not 
consider the investor's risk score, but rather allocates to a portfolio 
that best achieves the goal. 


Portfolio optimization configuration, required if allocation method - 
create. Information in opt config refers to security data, which must 
be created in advance using the Nucleus endpoints POST /security 
and POST /security price. opt config includes the fields shown 
below. 


A list of tickers to consider during the optimization process, referencing 
securities defined in the Nucleus API. We recommend using no more 
than 25 tickers in a single optimization. Pre-screening a securities 
universe prior to calling the service will result in faster execution times as 
well as more meaningful results. 


The minimum number of portfolio assets, excluding the cash security (if 
applicable). 


Weight constraints for security types, including w min major, 
w max major, w min minor, w max minor,and cash amount, 


which stipulate lower and upper bounds for minor and major 
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Parameter 


w asset config 


map 


sec types 


array, required 


start date 
date 


end date 
date 


allocations 
array(UUID) 


curr inv 


float, conditional requirement 
horizon 


integer, conditional requirement 


horizon frequency 


string, conditional requirement 


Hydrogen Proton API Reference 


Description 


Securities, as well as a constant weight for cash securities. Minimums 
are joined with zero to form a binary constraint. This means that the 
minimum weight of securities of each type may either be 0 or the 
stipulated minimum. For example, a w min major constraint of 5% 
indicates that if a major security is chosen during the optimization, its 
weight will be either 0% or >= 5%. 


Weight constraints for asset classes. Stipulates a maximum weight for 
the asset classes represented in tickers . If an asset class is 
represented in tickers but not found in w asset config, the weight 
for that asset class will not be constrained. 


A type for each security in tickers. Values may be major, minor, 
and cash. major securities are intended to be securities with more 
lenient weight thresholds. minor securities are intended to be securities 
with tighter weight thresholds. cash securities are constrained to a 
constant weight. major and minor designations interact with 

w config to set distinct weight constraints for different kinds of 
Securities. A maximum of one security may be labelled with the cash 


type. 


Start date for historical prices in yyyy-mm-dd format. 


End date for historical prices in yyyy-mm-dd format. 


List of allocation ids in the Nucleus API to select from. As a pre- 
requisite, must have values for the performance and volatility 
arguments within the chosen allocation id. Defaults to include all 
available allocations. 


The current amount invested toward the goal. 


The goal horizon, with a frequency defined by horizon frequency. For 
example, for a client that is looking to make a major purchase in 30 


years, use horizon - 30. 


The frequency in relation to the number defined in horizon, and at 
which to run the simulation. Must be one of the following: year, 


quarter, month, week, day. 
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Parameter 


goal config 


map, required 


goal_amount 
string, conditional 


requirement 


goal inflation 


integer 


deposit config 


array(map) 


dep start reference 


string 


dep start period 


integer 


dep end reference 


string 


dep end period 


integer 


dep amount 
float 


dep frequency 


string 


dep inflation 
float 
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Description 


Information to configure the accumulation goal amount. 


The target goal amount, in today's dollars. 


The annualized inflation rate for goal amount . Defaults to 0. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
fields shown below. 


The reference for the starting point of the deposit. May be a start or 
a end, which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a start. 


The starting period for the deposit, relative to dep start reference. A 
value of O corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start or 
a end, which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference. A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 


The frequency of the deposit. Must be one of the following: year, 


quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the deposit. Defaults to 0. 
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Parameter 


recommendation config 
map 


recommend 


boolean 


inv min 


float 


inv max 


float 


dep min 
float 


dep max 
float 


horizon min 


integer 


horizon max 


integer 


recommended inflation 


float 


recommend type 


string 


conf tgt 
float 


Hydrogen Proton API Reference 


Description 


Information to configure the goal recommendation engine, including the 
fields shown below. 


If true, generate a recommended action to improve goal probability. 
Recommendations are only generated if a goal is off-track. Defaults to 


true. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 


goal amount. 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
goal amount divided by horizon. 


The minimum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 


horizon. Defaults to 1. 


The maximum number of periods (defined by horizon frequency) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 


Defaults to horizon. 


The confidence target for goal achievement. conf tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
cases, the stipulated conf tgt may be impossible to achieve within the 
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Parameter 


n 
integer 


remove outliers 


boolean 


thresh type 


string 


thresh 


float 


withdrawal tax 
float 


trading days per year 
integer 

risk score 

integer 
adjust for compounding 


boolean 


compounding rate 
float 


use proxy data 


boolean 


Hydrogen Proton API Reference 
Description 


given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true , remove outlying results. If true , outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be perc or amnt. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
dollar-based goal deviation threshold. Defaults to perc . 


The goal deviation threshold value, corresponding to thresh type. 
Defaults to 0. 


The tax rate to apply to all withdrawals. Defaults to 0. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


The investor's risk score from 0 to 100, where 0 indicates minimum risk 


appetite and 100 indicates maximum risk appetite. 


If true, adjust periodic deposit amounts for compounding based on 
compounding rate. This applies when a deposits dep frequency is 
shorter than horizon frequency. Defaults to false. 


The annualized rate to use when approximating a compounding effect on 
deposits. This value must be defined and adjust for compounding 
must be true in order to activate compounding adjustment. Defaults to 
0. 


If true, incorporate proxy price data as defined at the Security level in 
the Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 
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Parameter 


NAV Ill 


market_data_source 
string 


client_id 


UUID, conditional requirement 


goal id 
UUID, conditional requirement 


create log 
boolean 


Example Response 


"current status": { 


Hydrogen Proton API Reference 


Description 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus, security price data 
is sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus client used to derive one or more of the following: 
curr inv, horizon, horizon frequency, and 

goal config.goal amount. If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


The ID of a Nucleus goal used to derive one or more of the 
following: curr inv, horizon, horizon frequency, and 
goal config.goal amount. If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 


"on track": false, 


"progress": 0.4, 


"goal probability": 0.5937, 


"goal achievement score": 66, 


"return details": 


"pr € 


{ 


"period earnings": 0, 


"period deposit": 0, 


"period withdrawal": 0, 


"cumulative earnings": 0, 


"cumulative deposits": 0, 


"cumulative withdrawals": 0, 
"ending balance": 10000 
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LL 1 n" : 1 


"period earnings": 353.71, 


NAV III 


"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 353.71, 
"cumulative deposits": 2000, 
"cumulative withdrawals": 0, 
"ending balance": 12353.71 

D 

Tura d 
"period earnings": 853.48, 
"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 1207.19, 
"cumulative deposits": 4000, 
"cumulative withdrawals": 0, 
"ending balance": 15207.19 

D 

E E a 
"period earnings": 1417.59, 
"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 2624.78, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 18624.78 

D 

"4": d 
"period earnings": 1569.72, 
"period deposit": 9, 
"period withdrawal": 0, 
"cumulative earnings": 4194.5, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 20194.5 

bo 

"5": 1 
"period earnings": 1914.63, 
"period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 6109.14, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 22109.14 
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D 
"adjusted goal amount": 25000, 
"final balance": 22109.14 


NAV III 


bo 
"recommended status": { 
"on track": true, 
"progress": 0.4, 
"goal probability": 0.9019, 
"goal achievement score": 100, 
"action": [ 
{ 
"value": 500, 
"freq_unit": "year", 
"value type": "recurring deposit" 


], 


"return details": { 

"Ə": { 
"period earnings": ®, 
"period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"cumulative deposits": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 

D 

E i 
"period_earnings": 382.47, 
"period_deposit": 2500, 
"period withdrawal": 0, 
"cumulative earnings": 382.47, 
"cumulative deposits": 2500, 
"cumulative withdrawals": 0, 
"ending balance": 12882.47 

J 

"2": À 
"period earnings": 957.58, 
"period deposit": 2500, 
"period withdrawal": 0, 
"cumulative earnings": 1340.05, 
"cumulative deposits": 5000, 
"cumulative withdrawals": 0, 
"ending balance": 16340.05 

D 

"2 s d 
"period earnings": 1404.76, 
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"adjusted goal amount": 25000, 
"final balance": 25040.5 


bo 


"period deposit": 2500, 
"period withdrawal": 0, 


Hydrogen Proton API Reference 


"cumulative earnings": 2744.81, 


"cumulative deposits": 7500, 


"cumulative withdrawals": 0, 
"ending balance": 20244.81 


bo 
"4": d 


"period earnings": 1802.08, 


"period deposit": 500, 
"period withdrawal": 0, 


"cumulative earnings": 4546.89, 


"cumulative deposits": 8000, 


"cumulative withdrawals": 0, 


"ending balance": 


ho 
"e T 


22546.89 


"period earnings": 1993.62, 


"period deposit": 500, 
"period withdrawal": 0, 


"cumulative earnings": 6540.5, 


"cumulative deposits": 8500, 


"cumulative withdrawals": 0, 
"ending balance": 25040.5 


"allocation": { 


ret 


": Bopp. 


"risk": 0.0665, 
"assets": [ 


IF 


"AGG", 
"AMZN", 
"CMCSA", 
"GOOGL", 
"KHC", 
"XOM" 


"weights": [ 


0.5, 
0.1, 
0.1, 
0.1, 
0.1, 
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L 


"identifier": null 


NAV Ill 


RESPONSE 


Field 


current_status 


on_track 


progress 


goal probability 


goal achievement score 


return details 


period earnings 


period deposit 


period withdrawal 


cumulative earnings 


cumulative deposits 


cumulative withdrawals 


Hydrogen Proton API Reference 


Description 


The current status of the goal. 


If true, the goal is on track. 


The goal progress percentage, defined as the current invested 
amount divided by the total target withdrawal amount over 


d horizon. 


The probability of achieving the goal with the given portfolio. 


Aratio of goal probability tothe conf tgt on a scale from 0 
to 100. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions or withdrawals 
are made. 


The deposit made for this period in the accumulation phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and including this 
period. 


The cumulative deposits made up to and including this period for 
the decumulation phase. 


The cumulative withdrawals made up to and including this period. 
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NAV Ill 


ending balance 


adjusted goal amount 


final balance 


recommended status 


on track 


progress 


goal probability 


goal achievement score 


action 


value 


freq unit 


value type 


return details 


period earnings 


period deposit 


period withdrawal 


Hydrogen Proton API Reference 


Description 


The ending balance, inclusive of earnings and contributions for the 
current period. 


The effective goal target amount, adjusted for taxes, inflation, and 
goal deviation threshold. 


The projected final balance from return details. 

The goal status based on the provided recommendation. 

If true, the goal is on track. 

The goal progress percentage, defined as the current invested 
amount divided by the total target withdrawal amount over 

d horizon. 


The probability of achieving the goal with the given portfolio. 


Aratio of goal probability tothe conf tgt on a scale from 0 
to 100. 


The recommended action. Actions represent additions to the current 
configuration. For example, a recommended recurring deposit of 
100 indicates 100 in addition to any existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions or withdrawals 
are made. 


The deposit made for this period in the accumulation phase. 


The withdrawal made for this period. 
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Field 


cumulative_earnings 


cumulative_deposits 


cumulative withdrawals 


ending balance 


adjusted goal amount 


final balance 


allocation 


ret 


risk 


assets 


weights 


identifier 


audit log id 


NUCLEUS DATA DEPENDENCIES 


Security 

Security Price 
Client 

Goal 

Account 

Account Allocation 


Hydrogen Proton API Reference 


Description 


The cumulative investment earnings made up to and including this 
period. 


The cumulative deposits made up to and including this period for 
the decumulation phase. 


The cumulative withdrawals made up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 


The effective goal target amount, adjusted for taxes, inflation, and 
goal deviation threshold. 


The projected final balance from return details. 


Information about the chosen portfolio, including risk and return. 


The portfolio annualized return. 


The portfolio annualized standard deviation. 


The securities in the created portfolio, returned if 
allocation method = create. 


The weights for each of the securities in the created portfolio, 
returned if allocation method = create. 


The allocation's id, returned if allocation method - select. 


The unique id of the audit log record created in Electron. Only 
returned when create log - true. 
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e Model 
e Portfolio 


NAV Ill 


Accumulation Goal Recommendation 


This service is a recommendation engine that generates actions to increase the likelinood of achieving an 
accumulation goal, based on portfolio attributes and a target goal amount. Available actions include various 
types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal 
recommended action that satisfies a goal confidence target, subject to the given constraints. 


HTTP REQUEST 


POST /goal_accumulation/recommendation 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


-d '{ 
"p ret": [0.09], 
"p risk": [0.05], 
"trading days per year": 252, 
"horizon": 5, 
"horizon frequency": "year", 
"deposit config": [ 
{ 
"dep start reference": "a start", 
"dep start period": 0, 
"dep end reference": "a start", 
"dep end period": 3, 
"dep amount": 2000, 
"dep frequency": "year", 
"dep inflation": 0.0 
} 
L 


"goal config": { 
"goal amount": 25000, 
"goal inflation": 0.0 
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D 


"recommendation config": { 


NAV Ill 


"inv min": ®, 
"inv max": 1000, 
"dep min": O0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 
D 
"curr inv": 10000, 
"recommend type": "recurring", 
"conf tgt": 0.9, 
"n": 1000, 
"remove outliers": true, 
"thresh type": "perc", 
"thresh": 60, 
"withdrawal tax": 0.0, 
"adjust for compounding": false, 
"compounding rate": 0.0 
)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/goal accumulation/recomn 


ARGUMENTS 


Parameter Description 


p ret The annual portfolio return per period. The length of the array must be 

array, required less than or equal to horizon. If it is less, values will be conformed to 
the number of time periods by persisting the last value. For example, 
[0.04, 0.06] would result in an implied p ret of [0.04, 0.06, 0.06, 0.06] 
for a simulation that spans four time periods. 


p risk The annual portfolio standard deviation per period. The length of the 

array, required array must be less than or equal to horizon . If itis less, values will be 
conformed to the number of time periods by persisting the last value. For 
example, [0.04, 0.06] would result in an implied p risk of [0.04, 0.06, 
0.06, 0.06] for a simulation that spans four time periods. 


curr inv The current amount invested toward the goal. 


float, conditional requirement 


horizon The goal horizon, with a frequency defined by horizon frequency. For 


integer, conditional requirement example, for a client that is looking to make a major purchase in 30 
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Parameter 


horizon frequency 


string, conditional requirement 


goal config 


map, required 


goal amount 
string, conditional 


requirement 


goal inflation 


integer 
deposit config 


array(map) 


dep start reference 


string 


dep start period 


integer 


dep end reference 


string 


dep end period 


integer 


dep amount 
float 


Hydrogen Proton API Reference 


Description 


years, use horizon - 30. 


The frequency in relation to the number defined in horizon, and at 
which to run the simulation. Must be one of the following: year, 
quarter, month, week, day. 


Information to configure the accumulation goal amount. 


The target goal amount, in today's dollars. 


The annualized inflation rate for goal amount . Defaults to 0. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
fields shown below. 


The reference for the starting point of the deposit. May be a start or 
a end , which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a start. 


The starting period for the deposit, relative to dep start reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start or 
a end, which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 
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Parameter 


dep frequency 
string 


dep inflation 
float 


recommendation config 


map 


inv min 


float 


inv max 
float 


dep min 
float 


dep max 
float 


horizon min 


integer 


horizon max 


integer 


recommended inflation 


float 


recommend type 


string 


conf tgt 
float 


Hydrogen Proton API Reference 


Description 


The frequency of the deposit. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the deposit. Defaults to 0. 


Information to configure the goal recommendation engine, including the 
fields shown below. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 


goal amount. 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
goal amount divided by horizon. 


The minimum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 1. 


The maximum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 
Defaults to horizon. 


The confidence target for goal achievement. conf tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
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Parameter 


n 


integer 


remove outliers 


boolean 


thresh type 
string 


thresh 


float 


withdrawal tax 
float 


trading days per year 


integer 


adjust for compounding 


boolean 


compounding rate 
float 


client id 


UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


cases, the stipulated conf tgt may be impossible to achieve within the 
given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true , remove outlying results. If true , outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be "perc" or “amnt”. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
dollar-based goal deviation threshold. Defaults to perc. 


The goal deviation threshold value, corresponding to thresh_type. 
Defaults to 0. 


The tax rate to apply to all withdrawals. Defaults to 0. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


If true , adjust periodic deposit amounts for compounding based on 
compounding rate. This applies when a deposits dep frequency is 
shorter than horizon frequency . Defaults to false. 


The annualized rate to use when approximating a compounding effect on 
deposits. This value must be defined and adjust for compounding 
must be true in order to activate compounding adjustment. Defaults to 
0. 


The ID of a Nucleus client used to derive one or more of the following: 
curr inv, horizon, horizon frequency, and 

goal config.goal amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 
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Parameter 


NAV Ill 


goal id 
UUID, conditional requirement 


create_log 
boolean 


Example Response 


"on track": true, 
"progress": 0.4, 


Hydrogen Proton API Reference 


Description 


The ID of a Nucleus goal used to derive one or more of the 
following: curr inv, horizon, horizon frequency, and 
goal config.goal amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 


"goal probability": 0.915, 


"goal achievement score": 100, 


"action": [ 


{ 


"value": 796.875, 


"freq unit": 


"year", 


"value type": "recurring deposit" 


L 
"return details": { 
"O": f 


"period earnings": 0, 


"period deposit": 0, 


"period withdrawal": 0, 


"cumulative earnings": 0, 


"cumulative deposits": 0, 


"cumulative withdrawals": 0, 
"ending balance": 10000 


D 
u 


"period earnings": 271.88, 
"period deposit": 2796.88, 
"period withdrawal": 0, 


"cumulative earnings": 271.88, 
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"cumulative deposits": 2796.88, 
"cumulative withdrawals": 0, 
"ending balance": 13068.75 


NAV III 


D 

E X 
"period earnings": 813.47, 
"period deposit": 2796.88, 
"period withdrawal": 0, 
"cumulative earnings": 1085.35, 
"cumulative deposits": 5593.75, 
"cumulative withdrawals": 0, 
"ending balance": 16679.1 

D 

"B t 
"period earnings": 1057.48, 
"period deposit": 2796.88, 
"period withdrawal": 0, 
"cumulative earnings": 2142.83, 
"cumulative deposits": 8390.62, 
"cumulative withdrawals": 0, 
"ending balance": 20533.46 

D 

"4": d 
"period earnings": 1364.75, 
"period deposit": 796.88, 
"period withdrawal": 0, 
"cumulative earnings": 3507.59, 
"cumulative deposits": 9187.5, 
"cumulative withdrawals": 0, 
"ending balance": 22695.09 


D 

"S S d 
"period earnings": 1735.93, 
"period deposit": 796.88, 
"period withdrawal": 0, 
"cumulative earnings": 5243.52, 
"cumulative deposits": 9984.38, 
"cumulative withdrawals": 0, 
"ending balance": 25227.89 


D 
"adjusted goal amount": 25000, 
"final balance": 25227.89 
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Field 


on_track 


progress 


goal probability 


goal achievement score 


action 


value 


freq unit 


value type 


return details 


period earnings 


period deposit 


period withdrawal 


cumulative earnings 


cumulative deposit 


cumulative withdrawals 


ending balance 


Hydrogen Proton API Reference 


Description 


If true , the goal is on track. 


The goal progress percentage, defined as the current invested amount 
divided by the target goal amount. 


The probability of achieving the goal with the given portfolio. 


Aratio of goal probability to the conf tgt on a scale from 0 to 
100. 


The recommended action. Actions represent additions to the current 
configuration. For example, a recommended recurring deposit of 100 
indicates 100 in addition to any existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 


Portfolio return information over the length of the horizon, broken down 
by period. 


The investment earnings for this period. Earnings are calculated at the 


beginning of each period, before contributions or withdrawals are made. 


The deposit made for this period in the accumulation phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and including this 
period. 


The cumulative deposits made up to and including this period for the 
accumulation phase. 


The cumulative withdrawals made up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 
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Field Description 


NAV Ill 


adjusted_goal_amount The effective goal target amount, adjusted for taxes, inflation, and goal 
deviation threshold. 


final_balance The projected final balance from return details. 


audit log id The unique id of the audit log record created in Electron. Only returned 
when create log = true. 


NUCLEUS DATA DEPENDENCIES 


e Client 

* Goal 

e Account 

e Account Allocation 

« Allocation 

* Allocation Composition 
e Model 

e Portfolio 


e Portfolio Asset Size 


Accumulation Goal Status 


This service analyzes the state of expected goal achievement for an accumulation goal, based on the current 
goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service 
provides other metrics for advanced analysis. This framework also has built-in support for a goal 
recommendation engine, which recommends actions that may be taken to increase the expected goal 
achievement probability if a goal is off track. 


HTTP REQUEST 


POST /goal accumulation/status 


Example Request 
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curl -X POST -H "Authorization: Bearer «access token>" \ 
-H "Content-Type: application/json" \ 
-d '( 
"p ret": [0.09], 
"p risk": [0.05], 
"trading days per year": 252, 


NAV III 


"horizon": 5, 

"horizon frequency": "year", 

"deposit config": [ 

{ 

"dep start reference": "a start", 
"dep start period": 0, 
"dep end reference": "a start", 
"dep end period": 3, 
"dep amount": 2000, 
"dep frequency": "year", 
"dep inflation": 0.0 


L 

"goal config": { 
"goal amount": 25000, 
"goal inflation": 0.0 

bo 

"recommendation config": { 
"recommend": true, 
"inv min": 0, 
"inv max": 1000, 
"dep min": 0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 


bo 

"curr inv": 10000, 

"recommend type": "recurring", 
"conf tgt": 0.9, 

"n": 1000, 


"remove outliers": true, 

"thresh type": "perc", 

"thresh": 60, 

"withdrawal tax": 0.0, 
"adjust for compounding": false, 
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"compounding rate": 0.0 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/goal accumulation/status 


ARGUMENTS 


Parameter 


p ret 


array, required 


p risk 


array, required 


curr inv 


float, conditional requirement 


horizon 


integer, conditional requirement 


horizon frequency 


string, conditional requirement 


goal config 


map, required 


goal amount 
string, conditional 


requirement 


goal inflation 


integer 


deposit config 


array(map) 


Description 


The annual portfolio return per period. The length of the array must be 
less than or equal to horizon . If it is less, values will be conformed to 
the number of time periods by persisting the last value. For example, 
[0.04, 0.06] would result in an implied p ret of [0.04, 0.06, 0.06, 0.06] 
for a simulation that spans four time periods. 


The annual portfolio standard deviation per period. The length of the 
array must be less than or equal to horizon. If it is less, values will be 
conformed to the number of time periods by persisting the last value. For 
example, [0.04, 0.06] would result in an implied p risk of [0.04, 0.06, 
0.06, 0.06] for a simulation that spans four time periods. 


The current amount invested toward the goal. 

The goal horizon, with a frequency defined by horizon frequency. For 
example, for a client that is looking to make a major purchase in 30 
years, use horizon - 30. 

The frequency in relation to the number defined in horizon, and at 
which to run the simulation. Must be one of the following: year, 


quarter, month, week, day. 


Information to configure the accumulation goal amount. 


The target goal amount, in today's dollars. 


The annualized inflation rate for goal amount . Defaults to 0. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
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Parameter 


dep start reference 


string 


dep start period 
integer 


dep end reference 


string 


dep end period 


integer 


dep amount 
float 


dep frequency 
string 


dep inflation 
float 


recommendation config 


map 


recommend 


boolean 


inv min 


float 


inv max 


Hydrogen Proton API Reference 


Description 


fields shown below. 


The reference for the starting point of the deposit. May be a start or 
a end , which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a start. 


The starting period for the deposit, relative to dep start reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start or 
a end , which refer to the start of the accumulation phase and the end of 
the accumulation phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 

The frequency of the deposit. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 

The annualized inflation rate for the deposit. Defaults to O. 

Information to configure the goal recommendation engine, including the 
fields shown below. 

If true, generate a recommended action to improve goal probability. 
Recommendations are only generated if a goal is off-track. Defaults to 


true. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 


goal amount. 
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dep_min 
float 


dep_max 
float 


horizon_min 


integer 


horizon_max 


integer 


recommended_inflation 


float 


recommend_type 


string 


conf_tgt 
float 


n 


integer 


remove_outliers 


boolean 


thresh_type 
string 
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Description 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
goal_amount divided by horizon. 


The minimum number of periods (defined by horizon_frequency ) that 
the accumulation horizon may be extended when recommend_type = 
horizon. Defaults to 1. 


The maximum number of periods (defined by horizon_frequency ) that 
the accumulation horizon may be extended when recommend_type = 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 
Defaults to horizon. 


The confidence target for goal achievement. conf_tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
cases, the stipulated conf_tgt may be impossible to achieve within the 
given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true, remove outlying results. If true, outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be "perc" or “amnt”. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
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Parameter 


thresh 
float 


withdrawal tax 
float 


trading days per year 


integer 


adjust for compounding 


boolean 


compounding rate 
float 


client id 
UUID, conditional requirement 


goal id 
UUID, conditional requirement 


create log 


boolean 


Example Response 


Hydrogen Proton API Reference 
Description 


dollar-based goal deviation threshold. Defaults to perc. 


The goal deviation threshold value, corresponding to thresh_type. 
Defaults to 0. 


The tax rate to apply to all withdrawals. Defaults to 0. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


If true , adjust periodic deposit amounts for compounding based on 
compounding rate. This applies when a deposits dep frequency is 
shorter than horizon frequency . Defaults to false. 


The annualized rate to use when approximating a compounding effect on 
deposits. This value must be defined and adjust for compounding 
must be true in order to activate compounding adjustment. Defaults to 
O: 


The ID of a Nucleus client used to derive one or more of the following: 
curr inv, horizon, horizon frequency, and 

goal config.goal amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


The ID of a Nucleus goal used to derive one or more of the 
following: curr inv, horizon, horizon frequency, and 
goal config.goal amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 
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"current status": { 
"on track": false, 
"progress": 0.4, 
"goal probability": 0.1638, 
"goal achievement score": 18, 
"return details": { 
"Ə": { 
"period earnings": ®, 
"period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"cumulative deposits": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 
D 
"Lo Y 
"period earnings": 274.26, 
"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 274.26, 
"cumulative deposits": 2000, 
"cumulative withdrawals": 0, 
"ending balance": 12274.26 
D 
Ze mcd 
"period earnings": 665.94, 
"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 940.19, 
"cumulative deposits": 4000, 
"cumulative withdrawals": 0, 
"ending balance": 14940.19 
D 
SC SEI 
"period earnings": 954.05, 
"period deposit": 2000, 
"period withdrawal": 0, 
"cumulative earnings": 1894.25, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 17894.25 
D 
"4": 1 
"period earnings": 1068.64, 
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"period deposit": 0, 
"period withdrawal": 0, 


NAV III 


"cumulative earnings": 2962.89, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 18962.89 

J 

"E" d 
"period earnings": 1479.72, 
"period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 4442.61, 
"cumulative deposits": 6000, 
"cumulative withdrawals": 0, 
"ending balance": 20442.61 


D 
"adjusted goal amount": 25000, 
"final balance": 20442.61 
D 
"recommended status": { 
"on track": true, 
"progress": 0.4, 
"goal probability": 0.9025, 
"goal achievement score": 100, 
"action": [ 
{ 
"value": 781.25, 
"freq unit": "year", 
"value type": "recurring deposit" 


IF 


"return details": ( 

"Ə": { 
"period earnings": 0, 
"period deposit": 9, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"cumulative deposits": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 

bo 

"1": { 
"period earnings": 302.11, 
"period deposit": 2781.25, 
"period withdrawal": 0, 
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"cumulative earnings": 302.11, 
"cumulative deposits": 2781.25, 


NAV III 


"cumulative withdrawals": 0, 
"ending balance": 13083.36 

D 

"gs H 
"period earnings": 749.04, 
"period deposit": 2781.25, 
"period withdrawal": 0, 
"cumulative earnings": 1051.14, 
"cumulative deposits": 5562.5, 
"cumulative withdrawals": 0, 
"ending balance": 16613.64 

D 

SEA 
"period earnings": 1059.19, 
"period deposit": 2781.25, 
"period withdrawal": 0, 
"cumulative earnings": 2110.34, 
"cumulative deposits": 8343.75, 
"cumulative withdrawals": 0, 
"ending balance": 20454.09 

D 

"4": d 
"period earnings": 1443.06, 
"period deposit": 781.25, 
"period withdrawal": 0, 
"cumulative earnings": 3553.4, 
"cumulative deposits": 9125, 
"cumulative withdrawals": 0, 
"ending balance": 22678.4 

bo 

"5": 1 
"period earnings": 1579.8, 
"period deposit": 781.25, 
"period withdrawal": 0, 
"cumulative earnings": 5133.2, 
"cumulative deposits": 9906.25, 
"cumulative withdrawals": 0, 
"ending balance": 25039.45 


J 
"adjusted_goal_amount": 25000, 
"final_balance": 25039.45 
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= } 
z } 
Z 
RESPONSE 
Field 


current_status 


on_track 


progress 


goal probability 


goal achievement score 


return details 


period earnings 


period deposit 


period withdrawal 


cumulative earnings 


cumulative deposit 


cumulative withdrawals 


ending balance 


Hydrogen Proton API Reference 


Description 


The current status of the goal. 


If true , the goal is on track. 


The goal progress percentage, defined as the current invested 
amount divided by the total target withdrawal amount over 


d horizon. 


The probability of achieving the goal with the given portfolio. 


Aratio of goal probability tothe conf tgt on a scale from 0 
to 100. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions or withdrawals 
are made. 


The deposit made for this period in the accumulation phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and including this 
period. 


The cumulative deposits made up to and including this period for 
the decumulation phase. 


The cumulative withdrawals made up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 
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Field 


NAV Ill 


adjusted goal amount 


final balance 


recommended status 


on track 


progress 


goal probability 


goal achievement score 


action 


value 


freq unit 


value type 


return details 


period earnings 


period deposit 


period withdrawal 


cumulative earnings 


Hydrogen Proton API Reference 


Description 


The effective goal target amount, adjusted for taxes, inflation, and 
goal deviation threshold. 


The projected final balance from return details. 


The goal status based on the provided recommendation. 


If true , the goal is on track. 


The goal progress percentage, defined as the current invested 
amount divided by the total target withdrawal amount over 


d horizon. 


The probability of achieving the goal with the given portfolio. 


Aratio of goal probability tothe conf tgt on a scale from 0 
to 100. 


The recommended action. Actions represent additions to the current 
configuration. For example, a recommended recurring deposit of 
100 indicates 100 in addition to any existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 


Portfolio return information over the length of the horizon, broken 
down by period. 


The investment earnings for this period. Earnings are calculated at 
the beginning of each period, before contributions or withdrawals 
are made. 

The deposit made for this period in the accumulation phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and including this 
period. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 251/440 


8/3/23, 5:09 PM 


Field 


NAV Ill 


cumulative_deposit 


cumulative_withdrawals 


ending balance 


adjusted goal amount 


final balance 


audit log id 


NUCLEUS DATA DEPENDENCIES 


e Client 

* Goal 

* Account 

* Account Allocation 

* Allocation 

e Allocation Composition 
e Model 

* Portfolio 

* Portfolio Asset Size 


Hydrogen Proton API Reference 


Description 


The cumulative deposits made up to and including this period for 
the decumulation phase. 


The cumulative withdrawals made up to and including this period. 


The ending balance, inclusive of earnings and contributions for the 
current period. 


The effective goal target amount, adjusted for taxes, inflation, and 
goal deviation threshold. 


The projected final balance from return details. 


The unique id of the audit log record created in Electron. Only 
returned when create log = true. 


Decumulation Goal Allocation 


This service offers a framework to match a decumulation goal to an appropriate portfolio, with the ability to 


prioritize an investor's risk appetite or prioritize the goal achievement. Allocations are selected from a universe 


based upon best fit for the selected priority, drawing from pre-defined portfolios and dynamically generated 


portfolios. This framework also has built-in support for a goal recommendation engine, which recommends 


actions that may be taken to increase the expected goal achievement probability if a goal cannot be achieved 


in the initially presented allocation context. 
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HTTP REQUEST 


POST /goal decumulation/allocation 


NAV III 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


-d '( 

"allocation method": "create", 

"allocation priority": "goal", 

"allocations": [ 
"406ec16e-ebae-4130-a6c0-1cacb72569a2", 
"740f6466-3300-4122-927d-4a691359fa32", 

"0a02058f -4046 -48de-b3d2-aeefd6d4efac" 
l 
"opt config": { 
"tickers": ["KHC", "AGG", "AMZN", "CMCSA", "XOM", 
"min assets": 6, 
"w config": ( 
"w min major": 0.05, 
"w max major": 1, 
"w min minor": 0.05, 
"w max minor": 0.1, 
"cash amount": 0.0 
D 
"w asset config": { 
"US Equities": 1.0, 
"Fixed Income": 1.0, 
"Intl Equities": 1.0, 
"EM Equities": 1.0, 
"Commodities": 1.0 
J 
"sec types": ["minor", "major","minor", "minor", "minor", "minor"], 
"start date": "2016-01-01", 
"end date": "2017-01-01" 
bo 


"risk score": 77, 
"trading days per year": 252, 
"a horizon": 3, 
"d horizon": 2, 
"horizon frequency": "year", 
"deposit config": [ 

{ 


"dep start reference": "a start", 
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= "dep start period": 0, 
a "dep end reference": "a start", 
= "dep_end_period": 3, 
"dep amount": 2000, 
"dep frequency": "year", 
"dep inflation": 0.0 
} 
L 
“withdrawal config": [ 
{ 
"with amount": 11000, 
"with start reference": "a end", 
"with start period": 0, 
"with end reference": "d end", 
"with end period": 0, 
"with frequency": "year", 
"with inflation": 0.0 
} 
L 
"recommendation config": { 
"recommend": true, 
"inv min": 0, 
"inv max": 1000, 
"dep min": 0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 
bo 
"curr inv": 10000, 
"recommend type": "recurring", 
"conf tgt”: 0,9, 
"n": 1000, 
"remove outliers": true, 
"thresh type": "perc", 
"thresh": 0, 
"withdrawal tax": 0.0, 
"adjust for compounding": false, 
"compounding rate": 0.0, 
"use proxy data": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/goal decumulation/alloce 
ARGUMENTS 
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Parameter 


NAV Ill 


allocation_method 


string, required 


allocation_priority 


string, required 


opt_config 


map, conditional requirement 


tickers 


array, required 


min_assets 


integer, required 


w_config 


map, required 


w_asset_config 


map 


Hydrogen Proton API Reference 


Description 


The allocation universe source, may be either create or select. 
create constructs an allocation universe from a dynamically generated 
efficient frontier, based on opt_config. select derives an allocation 
universe from pre-defined allocations, as stipulated by allocations. 


The priority to consider when deriving the appropriate allocation, may be 
risk or goal. risk finds a portfolio that corresponds to an investor’s 
risk_score within the universe of potential portfolios. goal does not 
consider the investor’s risk_score, but rather allocates to a portfolio 
that best achieves the goal. 


Portfolio optimization configuration, required if allocation_method = 
create. Information in opt_config refers to security data, which must 
be created in advance using the Nucleus endpoints POST /security 
and POST /security_price. opt_config includes the fields shown 
below. 


A list of tickers to consider during the optimization process, referencing 
securities defined in the Nucleus API. We recommend using no more 
than 25 tickers in a single optimization. Pre-screening a securities 
universe prior to calling the service will result in faster execution times as 
well as more meaningful results. 


The minimum number of portfolio assets, excluding the cash security (if 
applicable). 


Weight constraints for security types, including w min major, 

w max major, w min minor, w max minor, and cash amount, 
which stipulate lower and upper bounds for minor and major 
securities, as well as a constant weight for cash securities. Minimums 
are joined with zero to form a binary constraint. This means that the 
minimum weight of securities of each type may either be 0 or the 
stipulated minimum. For example, a w min major constraint of 596 
indicates that if a major security is chosen during the optimization, its 
weight will be either 0% or >= 5%. 


Weight constraints for asset classes. Stipulates a maximum weight for 
the asset classes represented in tickers. If an asset class is 
represented in tickers but not found in w asset config, the weight 


for that asset class will not be constrained. 
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NAV Ill 


Parameter 


sec_types 


array, required 


start_date 
date 


end_date 
date 


allocations 
array(UUID) 


curr_inv 


float, conditional requirement 


a_horizon 


integer, conditional requirement 


d_horizon 


integer, conditional requirement 


horizon_frequency 


string, conditional requirement 


withdrawal config 
array(map), conditional 


requirement 


Hydrogen Proton API Reference 


Description 


A type for each security in tickers . Values may be major, minor, 
and cash. major securities are intended to be securities with more 
lenient weight thresholds. minor securities are intended to be securities 
with tighter weight thresholds. cash securities are constrained to a 
constant weight. major and minor designations interact with 

w config to set distinct weight constraints for different kinds of 
securities. A maximum of one security may be labelled with the cash 


type. 


Start date for historical prices in yyyy-mm-dd format. 


End date for historical prices in yyyy-mm-dd format. 


List of allocation ids in the Nucleus API to select from. As a pre- 
requisite, must have values for the performance and volatility 
arguments within the chosen allocation id. Defaults to include all 
available allocations. 


The current amount invested toward the goal. 


The accumulation horizon, with a frequency defined by 
horizon frequency. For example, for a client that is looking to retire in 
30 years, use a horizon - 30. Must be greater than O if 


recommend type is recurring or combo. 


The decumulation horizon, with a frequency defined by 

horizon frequency. For example, for a client that is looking to take 
withdrawals for 25 years during retirement, use d horizon = 25. Must 
be greater than O. 


The frequency in relation to the numbers defined in a horizon and 
d horizon, and at which to run the simulation. Must be one of the 
following: year, quarter, month, week, day. 


The withdrawals to occur during the goal's decumulation phase. 
withdrawal config is an array of maps, with each map containing the 
fields shown below. 
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zi 
z 
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Parameter 


with_amount 
float, conditional requirement 


with_start_reference 


string 


with_start_period 


integer 


with_end_reference 


string 


with_end_period 


integer 


with_frequency 


string 


with_inflation 
float 


deposit config 


array(map) 


dep start reference 


string 


dep start period 


integer 


Hydrogen Proton API Reference 


Description 


The withdrawal amount, in today's dollars. 


The reference for the starting point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to a end. 


The starting period for the withdrawal, relative to 

with start reference.A value of O corresponds to the reference 
point, a positive number indicates a period after the reference point, and 
a negative number indicates a period before the reference point. 
Periodicity depends upon with frequency . Defaults to 0. 


The reference for the ending point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to d end. 


The ending period for the withdrawal, relative to with end reference. 
A value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
with frequency. Defaults to 0. 


The frequency of the withdrawal. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the withdrawal. Defaults to O. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
fields shown below. 


The reference for the starting point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a start. 


The starting period for the deposit, relative to dep start reference. A 
value of O corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
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zi 
z 


Parameter 


dep end reference 
string 


dep end period 


integer 


dep amount 
float 


dep frequency 


string 


dep inflation 
float 


recommendation config 


map 


recommend 


boolean 


inv min 


float 


inv max 


float 


dep min 


float 


dep max 
float 


Hydrogen Proton API Reference 


Description 


indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference. A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 


The frequency of the deposit. Must be one of the following: year , 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the deposit. Defaults to 0. 

Information to configure the goal recommendation engine, including the 
fields shown below. 

If true, generate a recommended action to improve goal probability. 


Recommendations are only generated if a goal is off-track. Defaults to 


true. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 


d horizon. 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 
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zi 
z 


Parameter 


horizon min 


integer 


horizon max 


integer 


recommended inflation 


float 


recommend type 


string 


conf tgt 
float 


n 


integer 


remove outliers 


boolean 


thresh type 


string 


thresh 
float 


Hydrogen Proton API Reference 


Description 


d horizon divided by a horizon. 


The minimum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 1. 


The maximum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 
Defaults to horizon. 


The confidence target for goal achievement. conf tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
cases, the stipulated conf tgt may be impossible to achieve within the 
given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true , remove outlying results. If true , outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be "perc" or “amnt”. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
dollar-based goal deviation threshold. Defaults to perc. 


The goal deviation threshold value, corresponding to thresh_type. 
Defaults to 0. 
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NAV Ill 


Parameter 


withdrawal tax 
float 


trading days per year 
integer 

risk score 

integer 
adjust for compounding 


boolean 


compounding rate 
float 


use proxy data 


boolean 


market data source 


string 


client id 


UUID, conditional requirement 


goal id 


UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


The tax rate to apply to all withdrawals. Defaults to O. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


The investor's risk score from 0 to 100, where 0 indicates minimum risk 


appetite and 100 indicates maximum risk appetite. 


If true , adjust periodic deposit amounts for compounding based on 
compounding rate. This applies when a deposits dep frequency is 
shorter than horizon frequency . Defaults to false. 


The annualized rate to use when approximating a compounding effect on 
deposits. This value must be defined and adjust for compounding 
must be true in order to activate compounding adjustment. Defaults to 
0. 


If true, incorporate proxy price data as defined at the Security level in 
the Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data 
is sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus client used to derive one or more of the following: 
curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


The ID of a Nucleus goal used to derive one or more of the following: 
curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 
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= Parameter Description 

> 

< 

= create_log If true, a record of this Proton request URL, request body, response 
boolean body, and Nucleus UUID(s), where applicable, will be stored in Electron 


as an audit log, and the resulting audit_log id will be returned in the 
Proton response. Defaults to false. 


Example Response 


"current status": { 
"on track": false, 
"progress": 0.4545, 
"goal probability": 0.8342, 
"goal achievement score": 93, 
"return details": { 
"ea": { 
"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"accumulation cumulative deposit": 0, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 
D 
"a": À 
"period earnings": 326.32, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 326.32, 
"accumulation cumulative deposit": 2000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 12326.32 
D 
EI 
"period earnings": 1033.7, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
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"period withdrawal": 0, 
"cumulative earnings": 1360.02, 


NAV III 


"accumulation cumulative deposit": 4000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 15360.02 

bo 

"ar: { 
"period earnings": 1245.48, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 2605.5, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 18605.5 

D 

"4A": { 
"period earnings": 1669.58, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 4275.09, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 11000, 
"ending balance": 9275.09 

D 

ART 
"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 9275.09, 
"cumulative earnings": 4275.09, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 20275.09, 
"ending balance": @ 


bs 


"accumulation balance": 18605. 5 
D 
"recommended status": { 

"on track": true, 

"progress": 0.4545, 
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"goal probability": 0.9065, 
"goal achievement score": 100, 


NAV III 


"action": [ 
{ 
"value": 218.75, 
"freq unit": "year", 


"value type": "recurring deposit 


L 
"return details": { 

"Ə": { 
"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"accumulation cumulative deposit": 0, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 

bo 

"1": { 
"period earnings": 355.11, 
"accumulation period deposit": 2218.75, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 355.11, 
"accumulation cumulative deposit": 2218.75, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 12573.86 

bo 

"2": { 
"period earnings": 1040.96, 
"accumulation period deposit": 2218.75, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 1396.07, 
"accumulation cumulative deposit": 4437.5, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 15833.57 

bo 

Wa À 
"period earnings": 1230.63, 
"accumulation period deposit": 2218.75, 
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"decumulation period deposit": 0, 
"period withdrawal": 0, 


NAV III 


"cumulative earnings": 2626.7, 
“accumulation cumulative deposit": 6656.25, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 

"ending balance": 19282.95 


D 

"4A": d 
"period earnings": 1864.12, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 4490.82, 
"accumulation cumulative deposit": 6656.25, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 11000, 
"ending balance": 10147.07 

D 

"bus À 
"period earnings": 988.6, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 5479.43, 
"accumulation cumulative deposit": 6656.25, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 22000, 
"ending balance": 135.68 

3 


bo 
"accumulation balance": 19282.95 
bo 
"allocation": { 
"ret": 0.1177, 
"risk": 0.0665, 
"assets": [ 
"AGG", 
"AMZN", 
"CMCSA", 
"GOOGL", 
"KHC", 
"XOM" 
L 
"weights": [ 
0.5, 
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Co 


0.1, 
0.1, 
0.1, 
0.1 

l» 

"identifier": null 

} 
} 
RESPONSE 
Field 


current_status 


on_track 


progress 


goal_probability 


goal_achievement_score 


return_details 


period_earnings 


accumulation_period_deposit 


decumulation_period_deposit 


period_withdrawal 
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Description 


The current status of the goal. 


If true, the goal is on track. 


The goal progress percentage, defined as the current 
invested amount divided by the total target withdrawal 


amount over d_horizon. 


The probability of achieving the goal with the given 
portfolio. 


Aratio of goal_probability tothe conf_tgt ona 
scale from 0 to 100. 


Portfolio return information over the length of the 
horizon, broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 
contributions or withdrawals are made. 


The deposit made for this period in the accumulation 
phase. 


The deposit made for this period in the decumulation 
phase. 


The withdrawal made for this period. 
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Field 


NAV Ill 


cumulative_earnings 


accumulation cumulative deposit 


decumulation cumulative deposit 


cumulative withdrawals 


ending balance 


accumulation balance 


recommended status 


on track 


progress 


goal probability 


goal achievement score 


action 


value 


freq unit 


value type 
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Description 


The cumulative investment earnings made up to and 
including this period. 


The cumulative deposits made up to and including this 
period for the accumulation phase. 


The cumulative deposits made up to and including this 
period for the decumulation phase. 


The cumulative withdrawals made up to and including 
this period. 


The ending balance, inclusive of earnings and 
contributions for the current period. 


The projected balance at the end of the accumulation 
horizon. 


The goal status based on the provided recommendation. 


If true, the goal is on track. 


The goal progress percentage, defined as the current 
invested amount divided by the total target withdrawal 
amount over d_horizon. 


The probability of achieving the goal with the given 
portfolio. 


Aratio of goal_probability tothe conf_tgt ona 
scale from 0 to 100. 


The recommended action. Actions represent additions to 
the current configuration. For example, a recommended 

recurring deposit of 100 indicates 100 in addition to any 

existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 
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= Field 

> 

« 

= return details 


period earnings 


accumulation period deposit 
decumulation period deposit 


period withdrawal 


cumulative earnings 
accumulation cumulative deposit 
decumulation cumulative deposit 
cumulative withdrawals 
ending balance 
accumulation balance 
allocation 


ret 
risk 


assets 
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Description 


Portfolio return information over the length of the 
horizon, broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 


contributions or withdrawals are made. 


The deposit made for this period in the accumulation 
phase. 


The deposit made for this period in the decumulation 
phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and 
including this period. 


The cumulative deposits made up to and including this 
period for the accumulation phase. 


The cumulative deposits made up to and including this 
period for the decumulation phase. 


The cumulative withdrawals made up to and including 
this period. 


The ending balance, inclusive of earnings and 
contributions for the current period. 


The projected balance at the end of the accumulation 
horizon. 


Information about the chosen portfolio, including risk and 


return. 


The portfolio annualized return. 


The portfolio annualized standard deviation. 


The securities in the created portfolio, returned if 
allocation_method = create. 
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Field 


weights 


identifier 


audit_log id 


NUCLEUS DATA DEPENDENCIES 


e Security 

e Security Price 

e Client 

e Goal 

e Account 

e Account Allocation 

e Allocation 

e Allocation Composition 
e Model 

e Portfolio 
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Description 


The weights for each of the securities in the created 
portfolio, returned if allocation method = create. 


The allocation's id, returned if allocation method = 


select. 


The unique id of the audit log record created in Electron. 


Only returned when create log = true. 


Decumulation Goal Recommendation 


This service is a recommendation engine that generates actions to increase the likelihood of achieving a 


decumulation goal, based on portfolio attributes and a target goal amount. Available actions include various 


types of cash inflows as well as goal horizon extension. The engine will attempt to find the minimal 


recommended action that satisfies a goal confidence target, subject to the given constraints. 


HTTP REQUEST 


POST /goal decumulation/recommendation 


Example Request 
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a curl -X POST -H "Authorization: Bearer «access token»" \ 
= -H "Content-Type: application/json" \ 
-d '( 
"p ret": [0.09], 
"p risk": [0.05], 
"trading days per year": 252, 
"a horizon": 3, 
"d horizon": 2, 
"horizon frequency": "year", 
"deposit config": [ 
{ 
"dep start reference": "a start", 
"dep start period": 0, 
"dep end reference": "a start", 
"dep end period": 3, 
"dep amount": 2000, 
"dep frequency": "year", 
"dep inflation": 0.0 
} 
L 
“withdrawal config": [ 
{ 
"with amount": 11000, 
"with start reference": "a end", 
"with start period": 0, 
"with end reference": "d end", 
"with end period": 0, 
"with frequency": "year", 
"with inflation": 0.0 
} 
L 
"recommendation config": { 
"inv min": 0, 
"inv max": 1000, 
"dep min": 0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 
bo 
"curr inv": 10000, 
"recommend type": "recurring", 
"conf tgt": 0.9, 
"n": 1000, 


"remove outliers": true, 
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NAV Ill 
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"thresh type": "perc", 


"withdrawal tax": 0.0, 


"adjust for compounding": false, 


"compounding rate": 0.0 


}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/goal decumulation/recomn 


ARGUMENTS 


Parameter 


p ret 


array, required 


p risk 


array, required 


curr inv 


float, conditional requirement 


a horizon 


integer, conditional requirement 


d horizon 


integer, conditional requirement 


horizon frequency 


string, conditional requirement 


Description 


The annual portfolio return per period. The length of the array must be 
less than or equal to the sum of a horizon and d horizon . If it is 
less, values will be conformed to the number of time periods by 
persisting the last value. For example, [0.04, 0.06] would result in an 
implied p ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four 
time periods. 


The annual portfolio standard deviation per period. The length of the 
array must be less than or equal to the sum of a horizon and 

d horizon. If it is less, values will be conformed to the number of time 
periods by persisting the last value. For example, [0.04, 0.06] would 
result in an implied p risk of[0.04, 0.06, 0.06, 0.06] for a simulation 
that spans four time periods. 


The current amount invested toward the goal. 


The accumulation horizon, with a frequency defined by 
horizon frequency. For example, for a client that is looking to retire in 
30 years, use a horizon - 30. Must be greater than O if 


recommend type is recurring or combo. 


The decumulation horizon, with a frequency defined by 

horizon frequency. For example, for a client that is looking to take 
withdrawals for 25 years during retirement, use d horizon = 25. Must 
be greater than O. 


The frequency in relation to the numbers defined in a horizon and 
d horizon, and at which to run the simulation. Must be one of the 
following: year, quarter, month, week, day. 
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Parameter 


NAV Ill 


withdrawal_config 
array(map), conditional 


requirement 


with_amount 
float, conditional requirement 


with_start_reference 


string 


with_start_period 


integer 


with_end_reference 


string 


with_end_period 


integer 


with_frequency 


string 


with_inflation 
float 


deposit config 


array(map) 


dep start reference 


string 
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Description 


The withdrawals to occur during the goal's decumulation phase. 
withdrawal config is an array of maps, with each map containing the 
fields shown below. 


The withdrawal amount, in today's dollars. 


The reference for the starting point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to a end. 


The starting period for the withdrawal, relative to 

with start reference.A value of O corresponds to the reference 
point, a positive number indicates a period after the reference point, and 
a negative number indicates a period before the reference point. 
Periodicity depends upon with frequency . Defaults to 0. 


The reference for the ending point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to d end. 


The ending period for the withdrawal, relative to with end reference. 
A value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
with frequency. Defaults to 0. 


The frequency of the withdrawal. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the withdrawal. Defaults to O. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
fields shown below. 


The reference for the starting point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a start. 
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Parameter 


dep start period 
integer 


dep end reference 


string 


dep end period 


integer 


dep amount 
float 


dep frequency 
string 


dep inflation 
float 


recommendation config 


map 


inv min 


float 


inv max 


float 


dep min 


float 


dep max 
float 
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Description 


The starting period for the deposit, relative to dep start reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 


The frequency of the deposit. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the deposit. Defaults to 0. 


Information to configure the goal recommendation engine, including the 
fields shown below. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 


d horizon. 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 


d horizon divided by a horizon. 
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Parameter 


horizon min 


integer 


horizon max 


integer 


recommended inflation 


float 


recommend type 


string 


conf tgt 
float 


n 


integer 


remove outliers 


boolean 


thresh type 
string 


thresh 
float 


Hydrogen Proton API Reference 


Description 


The minimum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 1. 


The maximum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 
Defaults to horizon. 


The confidence target for goal achievement. conf tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
cases, the stipulated conf tgt may be impossible to achieve within the 
given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true, remove outlying results. If true, outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be "perc" or “amnt”. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
dollar-based goal deviation threshold. Defaults to perc. 


The goal deviation threshold value, corresponding to thresh_type. 
Defaults to 0. 
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Parameter 


withdrawal tax 
float 


trading days per year 


integer 


adjust for compounding 


boolean 


compounding rate 


float 


client id 


UUID, conditional requirement 


goal id 
UUID, conditional requirement 


create log 


boolean 


Example Response 


"on track": true, 


"progress": 0.4545, 


Hydrogen Proton API Reference 


Description 


The tax rate to apply to all withdrawals. Defaults to O. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


If true , adjust periodic deposit amounts for compounding based on 
compounding rate. This applies when a deposits dep frequency is 
shorter than horizon frequency. Defaults to false. 


The annualized rate to use when approximating a compounding effect 
on deposits. This value must be defined and 
adjust for compounding must be true in order to activate 
compounding adjustment. Defaults to O. 


The ID of a Nucleus client used to derive one or more of the following: 
curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


The ID of a Nucleus goal used to derive one or more of the following: 
curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 


"goal probability": 0.9127, 
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{ 


Jo 
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"goal achievement score": 199, 
"action": [ 


"value": 625, 
"freq unit": "year", 
"value type": "recurring deposit" 


"return details": { 


"ng : 


bs 


"mq. 


D 


Hätte 


bo 


mans 


{ 

"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 


"accumulation cumulative deposit": 
"decumulation cumulative deposit": 


"cumulative withdrawals": 0, 
"ending balance": 10000 


( 


"period earnings": 261.03, 


"accumulation period deposit": 2625, 


"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 261.03, 


"accumulation cumulative deposit": 
"decumulation cumulative deposit": 


"cumulative withdrawals": 0, 
"ending balance": 12886.03 


{ 


"period earnings": 819.01, 


2625, 
e, 


"accumulation period deposit": 2625, 


"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 1080.04, 


"accumulation cumulative deposit": 
"decumulation cumulative deposit": 


"cumulative withdrawals": 0, 
"ending balance": 16330.04 


i 
"period earnings": 1006.41, 


5250, 
e, 


"accumulation period deposit": 2625, 


"decumulation period deposit": 0, 
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"period withdrawal": 0, 
"cumulative earnings": 2086.45, 


NAV Ill 


"decumulation cumulative deposit": 


"cumulative withdrawals": 0, 

"ending balance": 19961.45 
J 
ATII 

"period earnings": 1358.01, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 


"cumulative earnings": 3444.47, 


"accumulation cumulative deposit": 
"decumulation cumulative deposit": 


"cumulative withdrawals": 11000, 
"ending balance": 10319.47 
D 
TB: H 
"period earnings": 832.18, 
“accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 


"cumulative earnings": 4276.65, 


“accumulation cumulative deposit": 
"decumulation cumulative deposit": 


"cumulative withdrawals": 22000, 
"ending balance": 151.65 


D 


“accumulation balance": 19961.45 


RESPONSE 


"accumulation cumulative deposit": 
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7875, 
e, 


7875, 


7875, 
e, 


Field 


on track 


progress 
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Description 


If true, the goal is on track. 


The goal progress percentage, defined as the current 
invested amount divided by the total target withdrawal 
amount over d_horizon. 
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Field 


NAV Ill 


goal probability 


goal achievement score 


action 


value 


freq unit 


value type 


return details 


period earnings 


accumulation period deposit 


decumulation period deposit 


period withdrawal 


cumulative earnings 


accumulation cumulative deposit 


decumulation cumulative deposit 


cumulative withdrawals 


ending balance 
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Description 


The probability of achieving the goal with the given portfolio. 


Aratio of goal_probability tothe conf_tgt onascale 
from O to 100. 


The recommended action. Actions represent additions to the 
current configuration. For example, a recommended 
recurring deposit of 100 indicates 100 in addition to any 
existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 


Portfolio return information over the length of the horizon, 
broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 
contributions or withdrawals are made. 

The deposit made for this period in the accumulation phase. 
The deposit made for this period in the decumulation phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and 
including this period. 


The cumulative deposits made up to and including this 
period for the accumulation phase. 


The cumulative deposits made up to and including this 
period for the decumulation phase. 


The cumulative withdrawals made up to and including this 
period. 


The ending balance, inclusive of earnings and contributions 
for the current period. 
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Field 
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accumulation_balance 


audit_log id 


NUCLEUS DATA DEPENDENCIES 


* Client 

e Goal 

e Account 

e Account Allocation 

e Allocation 

* Allocation Composition 
e Model 

e Portfolio 

e Portfolio Asset Size 


Decumulation Goal Status 


This service analyzes the state of expected goal achievement for a decumulation goal, based on the current 
goal configuration and context. In addition to a raw indication of whether a goal is on or off track, the service 
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Description 


The projected balance at the end of the accumulation 
horizon. 


The unique id of the audit log record created in Electron. 


Only returned when create log - true. 


provides other metrics for advanced analysis. This framework also has built-in support for a goal 


recommendation engine, which recommends actions that may be taken to increase the expected goal 


achievement probability if a goal is off track. 


HTTP REQUEST 


POST /goal decumulation/status 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


dota 
"p ret": [0.09], 
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"p risk": [0.05], 
"trading days per year": 252, 


NAV III 


"a horizon": 3, 

"d horizon": 2, 

"horizon frequency": "year", 
"deposit config": [ 


{ 


"dep start reference": "a start", 


"dep start period": 0, 

"dep end reference": "a start", 
"dep end period": 3, 

"dep amount": 2000, 

"dep frequency": "year", 

"dep inflation": 0.0 


]; 


"withdrawal config": [ 
{ 

"with amount": 11000, 
"with start reference": "a end", 
"with start period": 0, 
"with end reference": "d end", 
"with end period": 0, 
"with frequency": "year", 
"with inflation": 0.0 


L 
"pecommendation config": ( 
"recommend": true, 
"inv min": 0, 
"inv max": 1000, 
"dep min": 0, 
"dep max": 1000, 
"horizon min": 1, 
"horizon max": 10, 
"recommended inflation": 0.0 


D 

"curr inv": 10000, 

"recommend type": "recurring", 
"conf tgt": 0.9, 

"n": 1000, 


"remove outliers": true, 
"thresh type": "perc", 
"thresh": 60, 

"withdrawal tax": 0.0, 


"adjust for compounding": false, 
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ARGUMENTS 


Parameter 


p_ret 


array, required 


p_risk 


array, required 


curr_inv 


float, conditional requirement 


a_horizon 


integer, conditional requirement 


d_horizon 
integer, conditional requirement 


horizon_frequency 


string, conditional requirement 


withdrawal config 
array(map), conditional 


requirement 
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"compounding rate": 0.0 
}' "https://[sandbox][api].hydrogenplatform.com/proton/vi/goal decumulation/status 


Description 


The annual portfolio return per period. The length of the array must be 
less than or equal to the sum of a horizon and d horizon . If itis 
less, values will be conformed to the number of time periods by 
persisting the last value. For example, [0.04, 0.06] would result in an 
implied p ret of [0.04, 0.06, 0.06, 0.06] for a simulation that spans four 
time periods. 


The annual portfolio standard deviation per period. The length of the 
array must be less than or equal to the sum of a horizon and 

d horizon . If it is less, values will be conformed to the number of time 
periods by persisting the last value. For example, [0.04, 0.06] would 
result in an implied p risk of[0.04, 0.06, 0.06, 0.06] for a simulation 
that spans four time periods. 


The current amount invested toward the goal. 


The accumulation horizon, with a frequency defined by 
horizon frequency. For example, for a client that is looking to retire in 
30 years, use a horizon - 30. Must be greater than O if 


recommend type is recurring or combo. 


The decumulation horizon, with a frequency defined by 

horizon frequency. For example, for a client that is looking to take 
withdrawals for 25 years during retirement, use d horizon = 25. Must 
be greater than O. 


The frequency in relation to the numbers defined in a horizon and 
d horizon, and at which to run the simulation. Must be one of the 
following: year, quarter, month, week, day. 


The withdrawals to occur during the goal's decumulation phase. 
withdrawal config is an array of maps, with each map containing the 
fields shown below. 
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Parameter 


with_amount 
float, conditional requirement 


with_start_reference 


string 


with_start_period 


integer 


with_end_reference 


string 


with_end_period 


integer 


with_frequency 


string 


with_inflation 
float 


deposit config 


array(map) 


dep start reference 


string 


dep start period 


integer 
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Description 


The withdrawal amount, in today's dollars. 


The reference for the starting point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to a end. 


The starting period for the withdrawal, relative to 

with start reference.A value of O corresponds to the reference 
point, a positive number indicates a period after the reference point, and 
a negative number indicates a period before the reference point. 
Periodicity depends upon with frequency . Defaults to 0. 


The reference for the ending point of the withdrawal. May be a end or 
d end, which refer to the end of the accumulation phase and the end of 
the decumulation phase, respectively. Defaults to d end. 


The ending period for the withdrawal, relative to with end reference. 
A value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
with frequency. Defaults to 0. 


The frequency of the withdrawal. Must be one of the following: year , 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the withdrawal. Defaults to O. 


The deposits to occur over the course of the goal horizon. 
deposit config is an array of maps, with each map containing the 
fields shown below. 


The reference for the starting point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a start. 


The starting period for the deposit, relative to dep start reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
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Parameter 


dep end reference 
string 


dep end period 


integer 


dep amount 
float 


dep frequency 


string 


dep inflation 
float 


recommendation config 


map 


recommend 


boolean 


inv min 


float 


inv max 


float 


dep min 


float 


dep max 
float 


Hydrogen Proton API Reference 


Description 


indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The reference for the ending point of the deposit. May be a start, 
a end,or d end, which refer to the start of the accumulation phase, 
the end of the accumulation phase, and the end of the decumulation 
phase, respectively. Defaults to a end. 


The ending period for the deposit, relative to dep end reference.A 
value of 0 corresponds to the reference point, a positive number 
indicates a period after the reference point, and a negative number 
indicates a period before the reference point. Periodicity depends upon 
dep frequency . Defaults to 0. 


The deposit amount, in today's dollars. Defaults to O. 


The frequency of the deposit. Must be one of the following: year, 
quarter, month, week, day. Defaults to year. 


The annualized inflation rate for the deposit. Defaults to 0. 

Information to configure the goal recommendation engine, including the 
fields shown below. 

If true, generate a recommended action to improve goal probability. 


Recommendations are only generated if a goal is off-track. Defaults to 


true. 


The lower bound for one-time deposit recommendations. Defaults to 0. 


The upper bound for one-time deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 


d horizon. 


The lower bound for recurring deposit recommendations. Defaults to 
0. 


The upper bound for recurring deposit recommendations. Defaults to 
the first with amount found in withdrawal config multiplied by 
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Parameter 


horizon min 


integer 


horizon max 


integer 


recommended inflation 


float 


recommend type 


string 


conf tgt 
float 


n 


integer 


remove outliers 


boolean 


thresh type 


string 


thresh 
float 


Hydrogen Proton API Reference 


Description 


d horizon divided by a horizon. 


The minimum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 1. 


The maximum number of periods (defined by horizon frequency ) that 
the accumulation horizon may be extended when recommend type - 
horizon. Defaults to 64. 


The annualized inflation rate attributed to a recommended recurring 
deposit. 


The type of recommended action. Value may be recurring, one- 
time, combo, or horizon. recurring returns a recurring periodic 
deposit. one-time returns a one-time deposit at the current time 
(occurring at time-zero, and reflected by an effective increase in the 
initial balance). combo returns a combination of recurring and one-time 
deposits. horizon returns a new accumulation horizon for the goal. 
Defaults to horizon. 


The confidence target for goal achievement. conf tgt indicates the 
level of statistical confidence that applies to the goal analysis. In some 
cases, the stipulated conf tgt may be impossible to achieve within the 
given goal parameters; in these cases, the service will attempt to come 
as close as possible to satisfying the confidence target. Defaults to 0.90. 


The number of simulations to run in the monte carlo simulation. Larger 

n values will make goal simulation results more consistent, but increase 
the execution time of the service. It has a maximum allowable value of 
10000. Defaults to 2000. 


If true , remove outlying results. If true , outlier analysis is performed 
on a median absolute deviation (MAD) basis, at the 2.5 MAD threshold. 
Defaults to true. 


The goal deviation threshold type. Value may be "perc" or “amnt”. perc 
indicates a percentage-based goal deviation threshold. amnt indicates a 
dollar-based goal deviation threshold. Defaults to perc. 


The goal deviation threshold value, corresponding to thresh_type. 
Defaults to 0. 
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Parameter 


withdrawal tax 
float 


trading days per year 


integer 


adjust for compounding 


boolean 


compounding rate 


Hydrogen Proton API Reference 


Description 


The tax rate to apply to all withdrawals. Defaults to O. 


The number of days per year for which a portfolio is subject to market 
fluctuation. trading days per year impacts goal simulation results 
when horizon frequency = day. Defaults to 252. 


If true , adjust periodic deposit amounts for compounding based on 


compounding rate. This applies when a deposits dep frequency is 


shorter than horizon frequency, as deposits are conformed to 
horizon frequency during the analysis. Defaults to false. 


The annualized rate to use when approximating a compounding effect 


float on deposits. This value must be defined and 
adjust for compounding must be true in order to activate 
compounding adjustment. Defaults to O. 

client id The ID of a Nucleus client used to derive one or more of the following: 


UUID, conditional requirement 


goal id 
UUID, conditional requirement 


create log 


boolean 


Example Response 


curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


The ID of a Nucleus goal used to derive one or more of the following: 
curr inv, a horizon, d horizon, horizon frequency, and 
withdrawal config.with amount . If one or more of these required 
parameters are not provided, both client id and goal id are 
required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 


"current status": { 
"on track": false, 
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"progress": 0.4545, 
"goal probability": 0.5298, 
"goal achievement score": 59, 


NAV III 


"return details": { 
"Os À 

"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
"accumulation cumulative deposit": 0, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 10000 


D 

“di À 
"period earnings": 302.11, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 302.11, 
"accumulation cumulative deposit": 2000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 12302.11 

D 

m2 -f 
"period earnings": 722.99, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 1025.1, 
"accumulation cumulative deposit": 4000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 15025.1 

D 

"2": d 
"period earnings": 971.45, 
"accumulation period deposit": 2000, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 1996.55, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
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"ending balance": 17996.55 
D 
as { 

"period earnings": 1275.95, 


NAV III 


"accumulation period deposit": 90, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 3272.5, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 11000, 
"ending balance": 8272.5 

D 

SEI 
"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 8272.5, 
"cumulative earnings": 3272.5, 
"accumulation cumulative deposit": 6000, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 19272.5, 
"ending balance": 0 


D 
"accumulation balance": 17996.55 
J 
"recommended status": { 
"on track": true, 
"progress": 0.4545, 
"goal probability": 0.9043, 
"goal achievement score": 100, 
"action": | 


{ 
"value": 593.75, 
"freq unit": "year", 
"value type": "recurring deposit" 
} 
L 
"return details": { 
"a": { 


"period earnings": 0, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 0, 
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"accumulation cumulative deposit": 0, 
"decumulation cumulative deposit": 0, 


NAV III 


"cumulative withdrawals": 0, 
"ending balance": 10000 

D 

e FEE 
"period earnings": 280.94, 
"accumulation period deposit": 2593.75, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 280.94, 
"accumulation cumulative deposit": 2593.75, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 12874.69 

D 

"2": { 
"period_earnings": 700.92, 
"accumulation_period_deposit": 2593.75, 
"decumulation period deposit": @, 
"period withdrawal": 0, 
"cumulative earnings": 981.86, 
"accumulation cumulative deposit": 5187.5, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 16169.36 

J 

SEI 
"period earnings": 1125.06, 
"accumulation period deposit": 2593.75, 
"decumulation period deposit": 0, 
"period withdrawal": 0, 
"cumulative earnings": 2106.92, 
"accumulation cumulative deposit": 7781.25, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 0, 
"ending balance": 19888.17 

D 

"4": d 
"period earnings": 1284.08, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 3391, 
"accumulation cumulative deposit": 7781.25, 
"decumulation cumulative deposit": 0, 
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"cumulative withdrawals": 11000, 


a "ending balance": 10172.25 
= J 
" 5 " . { 
"period earnings": 888.86, 
"accumulation period deposit": 0, 
"decumulation period deposit": 0, 
"period withdrawal": 11000, 
"cumulative earnings": 4279.86, 
"accumulation cumulative deposit": 7781.25, 
"decumulation cumulative deposit": 0, 
"cumulative withdrawals": 22000, 
"ending balance": 61.11 
} 
bo 
“accumulation balance": 19888.17 
} 
} 
RESPONSE 
Field Description 
current_status The current status of the goal. 
on_track If true, the goal is on track. 
progress The goal progress percentage, defined as the current 
invested amount divided by the total target withdrawal 
amount over d horizon. 
goal probability The probability of achieving the goal with the given 
portfolio. 
goal achievement score Aratio of goal probability tothe conf tgt ona 
scale from 0 to 100. 
return details Portfolio return information over the length of the 
horizon, broken down by period. 
period earnings The investment earnings for this period. Earnings are 


calculated at the beginning of each period, before 
contributions or withdrawals are made. 
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= Field Description 
> 
< 
zZ accumulation_period_deposit The deposit made for this period in the accumulation 
phase. 
decumulation_period_deposit The deposit made for this period in the decumulation 
phase. 
period_withdrawal The withdrawal made for this period. 
cumulative_earnings The cumulative investment earnings made up to and 


including this period. 


accumulation cumulative deposit The cumulative deposits made up to and including this 
period for the accumulation phase. 


decumulation cumulative deposit The cumulative deposits made up to and including this 
period for the decumulation phase. 


cumulative withdrawals The cumulative withdrawals made up to and including 
this period. 
ending balance The ending balance, inclusive of earnings and 


contributions for the current period. 


accumulation balance The projected balance at the end of the accumulation 
horizon. 
recommended status The goal status based on the provided recommendation. 
on track If true, the goal is on track. 
progress The goal progress percentage, defined as the current 


invested amount divided by the total target withdrawal 
amount over d horizon. 


goal probability The probability of achieving the goal with the given 
portfolio. 
goal achievement score Aratio of goal probability tothe conf tgt ona 


scale from 0 to 100. 


action The recommended action. Actions represent additions to 
the current configuration. For example, a recommended 
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Field 
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value 


freq_unit 


value type 


return details 


period earnings 


accumulation period deposit 


decumulation period deposit 


period withdrawal 


cumulative earnings 


accumulation cumulative deposit 


decumulation cumulative deposit 


cumulative withdrawals 


ending balance 


accumulation balance 
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Description 


recurring deposit of 100 indicates 100 in addition to any 
existing deposits. 


The value of the recommended action. 


The frequency unit of value. 


The type of recommendation being made. 


Portfolio return information over the length of the 
horizon, broken down by period. 


The investment earnings for this period. Earnings are 
calculated at the beginning of each period, before 


contributions or withdrawals are made. 


The deposit made for this period in the accumulation 
phase. 


The deposit made for this period in the decumulation 
phase. 


The withdrawal made for this period. 


The cumulative investment earnings made up to and 
including this period. 


The cumulative deposits made up to and including this 
period for the accumulation phase. 


The cumulative deposits made up to and including this 
period for the decumulation phase. 


The cumulative withdrawals made up to and including 
this period. 


The ending balance, inclusive of earnings and 
contributions for the current period. 


The projected balance at the end of the accumulation 
horizon. 
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audit log id The unique id of the audit log record created in Electron. 
Only returned when create log = true. 


NUCLEUS DATA DEPENDENCIES 


e Client 

e Goal 

* Account 

e Account Allocation 

* Allocation 

« Allocation Composition 
e Model 

e Portfolio 

* Portfolio Asset Size 


Performance Calculator 


Performance is tracked via a series of statistics and can be tracked at the client, account, portfolio, allocation, 
model, goal, security, or benchmark level. Statistics are pre-defined and can be obtained in the statistics 
resource table. 


Hydrogen uses two methods to calculate performance: 


IRR (Internal Rate of Return) 


IRR, also known as dollar-weighted return, calculates the performance of a portfolio while incorporating inflows 
and outflows. Therefore, the timing of deposits and withdrawals substantially affects the return rate, with larger 
cash movements having a greater impact on performance compared to smaller changes in cash. IRR is a 
useful tool to calculate the absolute return of a portfolio and for determining whether a portfolio is growing at a 
return necessary to meet an investment goal. Therefore, IRR is used mostly by Hydrogen for account and 
client-related performance measures. 


TWR (Time Weighted Return) 


TWR captures the true performance of a portfolio by removing the impact of cash inflows and outflows on the 
portfolio's return. It reflects the effects of portfolio composition on return, without considering the effects of the 
client's deposits or withdrawals. TWR captures the return of the very first investment into a portfolio. At 
Hydrogen, we use TWR for all performance calculations which do not have cash flows. This includes 
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Institute. Calculating returns using TWR is the better method of calculating a manager’s performance and 
analyzing the performance of a portfolio’s underlying assets. 


HTTP REQUEST 


POST /performance_calculator 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


ad td 


"account id": "f523d2b9-ceb8-4181-b794-40d15f720046", 
"stat name": "ann return" 


allocation, benchmark, model, and security performance, which do not change based on total assets invested 
in them. TWR is also required by the Global Investment Performance Standards (GIPS) published by the CFA 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/performance calculator 


ARGUMENTS 


Parameter 


account id 


UUID, conditional requirement 


allocation id 


UUID, conditional requirement 


benchmark id 


UUID, conditional requirement 


Description 


The ID of a Nucleus Account to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 

model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Allocation to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 
model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Benchmark to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 

model id, portfolio id,or security id. A benchmark id 
may be provided in addition to any of the IDs listed, but only for the 
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Parameter 


client id 


UUID, conditional requirement 


goal id 


UUID, conditional requirement 


household id 
UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 


UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


following statistics: beta, treynor ratio, alpha, correlation, 
covariance, r squared, information ratio, 

tracking error, active premium, up pct ratio, 
down pct ratio, pct gain ratio, tstat, down capture, or 


up capture. 


The ID of a Nucleus Client to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 
model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Goal to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 

model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Household to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 

model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Model to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 
model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The ID of a Nucleus Portfolio to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 

model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 
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Parameter 


security_id 
UUID, conditional requirement 


stat_name 


string, required 


start_date 
date 


end_date 
date 


period type 


string 


n rolling volatility 
integer 


n day returns 


integer 


moving average 


integer 


annualized return period 


string 


active premium period 


string 


hist factor 
float 


var conf interval 
float 


n rolling max drawdown 


integer 
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Description 


The ID of a Nucleus Security to analyze. Conditionally required to 
provide only one of the following: account id, allocation id, 
benchmark id, client id, goal id, household id, 
model id, portfolio id,or security id. For certain statistics, 
a benchmark id may be provided in addition to any of the IDs 
listed. 


The statistic you want to run on the Nucleus entity. See Statistics for 
all available options. 


Start date for the period for which to calculate the statistic. 


End date for the period for which to calculate the statistic. 


Period to carry out statistic. Options are Y for annually, Q for 
quarterly, M for monthly, D for daily (must use capital letters) 


If stat 


rolling n day vol, number of days. Default is 7. 


If stat = rolling n day return, number of days. Default is 7. 


If stat = moving avg n day, number of days. Default is 7. 


If stat = ann return, period to calculate return. Default is D. 


If stat = active premium, period to calculate return. Default is D. 


If stat = histogram, number of data bins. Default is 5. 


If stat = var, confidence interval for the var. 


If stat = rolling n day max drawdown , number of days. Default 
ISG 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 


294/440 


8/3/23, 5:09 PM 


A 
z 


Parameter 


risk free sharpe 
float 


risk free treynor 
float 


risk free alpha 
float 


risk free sortino 
float 


mar down side deviation 
float 


num sim monte carlo 


integer 


n path monte carlo 
integer 


max percentile monte carlo 
float 


min percentile monte carlo 
float 


mean percentile monte carlo 
float 


Example Response 


a 


"ann return": 


RESPONSE 


0.061323 
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Description 


If stat = sharpe ratio, risk free rate of return. Default is 0. 


If stat = treynor ratio, risk free rate of return. Default is 0. 


If stat = alpha, risk free rate of return. Default is ®. 


If stat = sortino ratio, risk free rate of return. Default is 0. 


If stat = downside deviation, minimum acceptable return. 


Default is 0. 


If stat = monte carlo, number of Monte Carlo simulations. 
Default is 1880. 


If stat = monte carlo, number of Monte Carlo paths. Default is 
100. 


If stat = monte carlo, maximum probability for a Monte Carlo 


simulation. Default is 95 . 


If stat = monte carlo, minimum probability for a Monte Carlo 


simulation. Default is 5. 


If stat = monte carlo, mean probability for a Monte Carlo 
simulation. Default is 50 . 


98215253243 
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Field Description 
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(stat name) Value of the statistic for the given stat name. The name of this field will always match 
the stat_name provided in the request. 


NUCLEUS DATA DEPENDENCIES 


e Client 

e Business 

* Household 

* Account 

* Portfolio 

e Portfolio Asset Size 
« Allocation 

e Model 

e Model Asset Size 
e Benchmark 

e Goal 

* Security 


* Security Price 


Personal Financial Management 


Budget Calculator 


Budget Calculator analyzes a client's spending patterns against pre-defined budgets over time. This is useful 
to gain a deeper understanding of how closely a client follows a particular budget. A breakdown of each 
underlying budget item also provides helpful data to aid clients in staying on track and achieving their 
budgetary goals. 


HTTP REQUEST 


POST /budget calculator 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" ^ 
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-d éi 
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"budget_id": "790c936b-015d-4d8a-82ed-434a4bbc13e8", 
"as_of_date": "2016-12-22", 
"lookback periods": 3 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/budget calculator" 


ARGUMENTS 


Parameter 


budget id 


UUID, conditional requirement 


scope 


string 


transaction status scope 


array[string] 


currency conversion 
string 


as of date 
date 


lookback periods 


integer 


Description 


The ID of the Nucleus Budget. Please note that this service is not 
compatible with budgets that have a frequency unit of semi- 
monthly . Required if budget details is not provided. 


The scope of data to be considered. Value must be one of the 
following: all, external, internal. Defaults to all, which will 
consider internal data, or Accounts, Portfolios, and Portfolio 
Transactions, along with external data, or Aggregation Accounts 
and Aggregation Account Transactions. Only applicable when 
neither account ids or aggregation accounts is populated via 
budget details orthe Nucleus Budget record indicated by 
budget id. 


If populated, only transactions whose status matches one of the 
array values are considered in the analysis. Defaults to null, 
meaning all transactions are considered regardless of the status. 


The alphabetic currency code used to conduct the analysis, limited 
to 3 characters. Records will be converted from their original 
currency to the one indicated here. Conversions are supported both 
to and from the following currency codes: USD, GBP, EUR, AUD, 
CAD, CHF. See Currencies. Only applicable when a budget id is 
provided. 


Reference date of the analysis. Calculations will run through the 
earlier of this date and budget.end date as defined in Nucleus. 
Defaults to today's date. 


Number of lookback periods to analyze. Each period length is 
defined by the combination of budget.frequency and 
budget.frequency unit as defined in Nucleus, and period dates 
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Parameter 


show budget track 
boolean 


show average spend 


boolean 


only cleansed 


boolean 


budget details 


map, conditional requirement 


client id 


UUID, required 


account id 
UUID 


aggregation accounts 


array[map] 


aggregation account id 
UUID, required 


frequency unit 


string, required 


frequency 


integer 


currency code 


string 


total value 


float, conditional requirement 
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Description 


are set on a discrete calendar basis. A value of 0 would reflect only 
the current (partial) period containing as of date. Defaults to 1. 


If true, return the budget track response, an analysis of 
spending versus budget for each budget period. Defaults to true. 


If true , return the average spend response, an analysis of 
average spending values for each budget component and in total 


across the time periods analyzed. Defaults to false. 


If true , only Portfolio Transactions with the is cleansed 
parameter set to true will be considered. Defaults to false. 


Raw budget details that can be provided in place of a budget id. 


Allows the analysis to be run without creating a Budget in Nucleus. 


This field is required if budget id is not provided. 


The ID of the Nucleus Client the budget belongs to. 


The ID of the Nucleus Account associated with the budget. 


List of Nucleus Aggregation Accounts associated with the budget. 


The ID of the Nucleus Aggregation Account mapped to the budget. 


Frequency of the budget. Value may be daily, weekly, bi- 
weekly, monthly, quarterly,or annually. 


Number of frequency unit between each budget. For example, if 


the frequency unit is weekly and the frequency is 2, this 
means the budget occurs every two weeks. Default is 1. 


The alphabetic currency code used to conduct the analysis, limited 
to 3 characters. Only records with this currency code will be 


considered. Defaults to USD. See Currencies. 


Total value of the budget. Required if budget is not provided. 
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= Parameter Description 
z 
= budget List of budget components and their values. Required if 
array[map], conditional total_value is not provided. 
requirement 
category Category of the budget component. 


string, required 


subcategory Subcategory of the budget component. 
string 
value Value of the budget component. 


float, required 


start_date The start date for the budget. If not provided, defaults to today’s 
date date. 

end_date The end date for the budget. 

date 


Example Response 


"currency code": "USD", 
"budget track": [ 
{ 

"period start": "2016-10-01", 
"period end": "2016-10-31", 
"total funds budgeted": 100.0, 
"total funds spent": 56.51, 
"total funds remaining": 43.49, 
"budget components": [ 


{ 
"category": "Food & Dining", 
"subcategory": "Alcohol & Bars", 
"funds budgeted": 50.0, 
"funds spent": 0, 
"funds remaining": 50.0 

bo 

{ 


"category": "Health & Fitness", 
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= "subcategory": "Sports", 
a "funds budgeted": 50.0, 
= "funds spent": 56.51, 
"funds remaining": -6.51 
} 
] 
bo 
{ 
"period start": "2016-11-01", 
"period end": "2016-11-30", 
"total funds budgeted": 100.0, 
"total funds spent": 0, 
"total funds remaining": 100.0, 
"budget components": [ 
{ 
"category": "Food & Dining", 
"subcategory": "Alcohol & Bars", 
"funds budgeted": 50.0, 
"funds spent": 0, 
“funds remaining": 50.0 
ig 
{ 
"category": "Health & Fitness", 
"subcategory": "Sports", 
"funds budgeted": 50.0, 
"funds spent": 0, 
"funds remaining": 50.0 
j 
] 
bo 
{ 


"period start": "2016-12-01", 
"period end": "2016-12-22", 
"total funds budgeted": 100.0, 
"total funds spent": 284.77, 
"total funds remaining": -184.77, 
"budget components": [ 


{ 
"category": "Food & Dining", 
"subcategory": "Alcohol & Bars", 
"funds budgeted": 50.0, 
"funds spent": 284.77, 
"funds remaining": -234.77 

bo 

{ 


"category": "Health & Fitness", 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 300/440 


8/3/23, 5:09 PM 


NAV Ill 


Hydrogen Proton API Reference 


"subcategory": "Sports", 
"funds budgeted": 50.0, 
"funds spent": 0, 


"funds remaining": 50.0 


RESPONSE 


Field 


currency code 


budget track 


period start 


period end 


total funds budgeted 


total funds spent 


total funds remaining 


percent spent 


percent remaining 


budget components 


category 


subcategory 


funds budgeted 


Description 


Currency code associated with monetary response values. 


Analysis of spending versus budget for each budget period 


Start date of the budget period. 


End date of the budget period. 


Total amount of funds originally budgeted. 


Total amount of funds spent. 


Total amount of funds remaining, i.e. the delta between 
total funds budgeted and total funds spent. 


Total percent of funds spent. 


Total percent of funds remaining. 


Details for each item defined under the budget. 


The budget component's spending category. 


The budget component's spending subcategory. 


Amount of funds originally budgeted. 
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Field 


NAV Ill 


funds spent 


funds remaining 


percent spent 


percent remaining 


average spend 


total 


budget components 


category 


subcategory 


value 


NUCLEUS DATA DEPENDENCIES 


* Client 

* Account 

e Portfolio 

e Portfolio Transaction 
* Aggregation Account 


Hydrogen Proton API Reference 


Description 


Amount of funds spent. 


Amount of funds remaining, i.e. the delta between funds budgeted 
and funds spent. 


Percent of funds spent. 


Percent of funds remaining. 


Analysis of average spending values for each budget component and in 


total across the time periods analyzed. 


Total average amount of funds spent. 


Details of average spending values for each budget component. 


Category of the budget component. 


Subcategory of the budget component. 


Average amount of funds spent for the budget component. 


* Aggregation Account Transaction 


* Budget 
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< Cash Flow Analysis 
Cash Flow Analysis provides a benchmarked view of a client's cash flows over time, including income, 
spending, and net cash flow values. This tool is useful for charting cash flows trends over time, as well as for 
displaying helpful details about a client's spending habits. Tracking these cash flow values against a 
benchmark time period allows for insight into how the client's cash flow situation is changing relative to 
previous behavior. 
HTTP REQUEST 
Example Request 
POST /cash flow analysis 
curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"client id": "a32a48f7-d30e-489b-9d2b-576a3939343f", 
"scope": "all", 
"currency code": "USD", 
"start date": "2015-06-15", 
"end date": "2015-06-17", 
"show history": true, 
"show spending details": true, 
"show income details": true, 
"only cleansed": true 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/cash flow analysis" 
ARGUMENTS 
Parameter Description 
client id The ID of a Nucleus client whose data to analyze. Conditionally required 
UUID, conditional requirement if one of household id, account ids,or 


aggregation account ids is not provided. 
household id The ID of a Nucleus household whose data to analyze. Conditionally 


UUID, conditional requirement required if one of client id, account ids,or 


aggregation account ids is not provided. 
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Parameter 


account_ids 
array[UUID], conditional 


requirement 


aggregation_account_ids 
array[UUID], conditional 


requirement 


scope 


string 


transaction_status_scope 


array[string] 


currency_code 


string 


currency_conversion 


string 


start_date 
date 


end_date 
date 


benchmark_start_date 
date 


Hydrogen Proton API Reference 


Description 


ID(s) of the Nucleus Account(s) whose data to analyze. Conditionally 
required if one of client id, household_id, or 


aggregation_account_ids is not provided. 


An array of ID(s) of Nucleus Aggregation Account(s) whose data to 
analyze. Conditionally required if one of client id, household_id, or 


account_ids is not provided. 


The scope of data to be considered. Value must be one of the following: 
all, external, internal. Defaults to all , which will consider 
internal data, or Accounts, Portfolios, and Portfolio Transactions, 
along with external data, or Aggregation Accounts and Aggregation 
Account Transactions. Only applicable when client_id or 
household_id is passed. 


If populated, only transactions whose status matches one of the array 
values are included in the analysis. Defaults to null , meaning all 
transactions are included regardless of the status. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Only records with this currency code will be considered. 
Defaults to USD if currency_conversion is not provided. If 
currency_conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Records will be converted from their original currency to the 
one indicated here. Conversions are supported both to and from the 
following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


Start date of the analysis period. Defaults to the earliest available 
transaction date. 


End date of the analysis period. Defaults to the latest available 
transaction date. 


Start date of the benchmark analysis period. Default values for 
benchmark_start_date and benchmark_end_date are based on the 
difference between start_date and end_date. For example, if 
start date and end date are 2016-06-15 and 2016-06-17, 
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= Parameter 
> 
a 
z 


benchmark_end_date 
date 


show_history 


boolean 


show_spending details 


boolean 


show_income_details 
boolean 


only_cleansed 


boolean 


Example Response 


"currency code": 
"income summary": { 
"total": 0.0, 


Hydrogen Proton API Reference 


Description 


respectively, benchmark start date and benchmark end date 
default to 2016-06-12 and 2016-06-14, respectively. 


End date of the benchmark analysis period. Default values for 
benchmark start date and benchmark end date are based on the 
difference between start date and end date For example, if 
start date and end date are 2016-06-15 and 2016-06-17, 
respectively, benchmark start date and benchmark end date 
default to 2016-06-12 and 2016-06-14, respectively. 


If true , return a daily history of the client's cash flow details within the 
specified date range. Defaults to false. 


If true , return advanced spending details including breakdowns by 
category and by merchant as well as any outlying expenditures. Outlier 
analysis is performed on a median absolute deviation (MAD) basis, at 
the 2.5 threshold. Defaults to false. 


If true , return advanced income details including breakdowns by 
category and by merchant as well as any outlying inflows. Outlier 
analysis is performed on a median absolute deviation (MAD) basis, at 
the 2.5 threshold. Defaults to false. 


If true , only Portfolio Transactions with the is cleansed parameter 
setto true will be considered. Defaults to false. 


"USp" F 


"benchmark total": 0.0, 


"change": { 


"value": 0.0, 


"percentage": null 


bo 


"spending summary": { 
266.35, 


"total": 
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"benchmark total": 460.96, 
"change": { 

"value": -194.61, 

"percentage": -0.4222 


NAV III 


bo 
"net summary": { 
"total": -266.35, 
"benchmark total": -460.96, 
"change": { 
"value": 194.61, 
"percentage": -0.4222 


D 
"history": [ 
{ 

"date": "2015-06-15", 
"period income": 0.0, 
"period spending": 0.0, 
"period net": 0.0, 
"cumulative income": 0.0, 
"cumulative spending": 0.0, 
"cumulative net": 0.0 


"date": "2015-06-16", 
"period income": 0.0, 
"period spending": 0.0, 
"period net": 0.0, 
"cumulative income": 0.0, 
"cumulative spending": 0.0, 
"cumulative net": 0.0 


"date": "2015-06-17", 

"period income": 0.0, 

"period spending": 266.35, 
"period net": -266.35, 
"cumulative income": 0.0, 
"cumulative spending": 266.35, 
"cumulative net": -266.35 


IF 


"benchmark history": [ 


{ 
"date": "2015-06-12", 
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"period income": 0.0, 
"period spending": 0.0, 


NAV III 


"period net": 0.0, 
"cumulative income": 0.0, 
"cumulative spending": 0.0, 
"cumulative net": 0.0 


"date": "2015-06-13", 

"period income": 0.0, 

"period spending": 270.96, 
"period net": -270.96, 
"cumulative income": 0.0, 
"cumulative spending": 270.96, 
"cumulative net": -270.96 


"date": "2015-06-14", 

"period income": 0.0, 

"period spending": 190.0, 
"period net": -190.0, 
"cumulative income": 0.0, 
"cumulative spending": 460.96, 
"cumulative net": -460.96 


l 
"spending_details": { 
"by_category": [ 
{ 
"category": "Food & Dining", 
"value": 266.35, 
"benchmark value": 0.0, 
"change": { 
"value": 266.35, 
"percentage": null 
bo 
"weight": 1.9, 
"benchmark weight": 0.0, 
"subcategories": [ 


( 


"subcategory": "Restaurants", 


"value": 266.35, 
"benchmark value": 0.0, 
"change": { 
"value": 266.35, 
"percentage": null 
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D 


z "weight": 1.0, 
= "benchmark weight": 0.0 
} 
] 
bo 
{ 
"category": "Business Services", 
"value": 0.0, 
"benchmark value": 270.96, 
"change": { 
"value": -270.96, 
"percentage": -1.0 
bo 
"weight": 0.0, 
"benchmark weight": 0.5878, 
"subcategories": [ 
{ 
"subcategory": "Legal", 
"value": 0.0, 
"benchmark_value": 270.96, 
"change": { 
"value": -270.96, 
"percentage": -1.0 
bo 
"weight": 0.0, 
"benchmark weight": 1.0 
} 
] 
bo 
{ 


"category": "Health & Fitness", 
"value": 0.0, 
"benchmark value": 190.0, 


"change": { 
"value": -190.0, 
"percentage": -1.0 
bo 


"weight": 0.0, 

"benchmark weight": 0.4122, 

"subcategories": [ 

{ 

"subcategory": "Health Insurance", 
"value": 0.0, 
"benchmark value": 190.0, 
"change": { 
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]; 
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"value": -190.0, 
"percentage": -1.0 


J 
"weight": 0.0, 
"benchmark weight": 1.0 


"by merchant": [ 


( 


]; 


"merchant": "Isdom", 
"value": 266.35, 
"benchmark value": 0.0, 
"change": { 
"value": 266.35, 
"percentage": null 
bo 
"weight": 1.0, 
"benchmark weight": 0.0 


"merchant": "Blackzim", 
"value": 0.0, 
"benchmark value": 270.96, 


"change": { 
"value": -270.96, 
"percentage": -1.0 
J 


"weight": 0.0, 
"benchmark weight": 0.5878 


"merchant": "Geojaycare", 
"value": 0.0, 
"benchmark value": 190.0, 


"change": { 
"value": -190.0, 
"percentage": -1.0 
J 


"weight": 0.0, 
"benchmark weight": 0.4122 


"outliers": [] 


D 
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"income details": { 


[] 


z "by_category": [], 
z "by merchant": [], 
"outliers": 
} 
} 
RESPONSE 
Field 


currency code 


income summary 


total 


benchmark total 


change 


value 


percentage 


spending summary 


total 


benchmark total 


change 


value 


percentage 


net summary 


Hydrogen Proton API Reference 


Description 


Currency code associated with monetary response values. 


List of the total income values and the calculated delta between overall 


and benchmark. 


Total cash inflows over the trend period. 


Total cash inflows over the benchmark trend period. 


Difference in total cash inflows between the trend period and the 
benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


List of the total spending values and the calculated delta between 
overall and benchmark. 


Total cash outflows over the trend period. 


Total cash outflows over the benchmark trend period. 


Difference in total cash outflows between the trend period and the 
benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


List of the total net values and the calculated delta between overall and 


benchmark. 
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Field 


total 


benchmark_total 


change 


value 


percentage 


history 


date 


period income 


period spending 


period net 


cumulative income 


cumulative spending 


cumulative net 


benchmark history 


date 


period income 


period spending 


period net 


cumulative income 


cumulative spending 


cumulative net 
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Description 


Total net cash flows over the trend period. 


Total net cash flows over the benchmark trend period. 


Difference in total net cash flows between the trend period and the 
benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


List of income, spending and net values calculated by day. 


Date of the spending history record. 


Cash inflows during the period. 


Cash outflows during the period. 


Net cash inflows (outflows) during the period. 


Cumulative cash inflows up to and including this period. 


Cumulative cash outflows up to and including this period. 


Cumulative net cash inflows (outflows) up to and including this period. 


List of benchmark income, spending and net values calculated by day. 


Date of benchmark spending history record. 


Cash inflows during the period 


Cash outflows during the period. 


Net cash inflows (outflows) during the period. 


Cumulative cash inflows up to and including this period. 


Cumulative cash outflows up to and including this period. 


Cumulative net cash inflows (outflows) up to and including this period. 
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Field 
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spending details 


by_category 


category 


value 


benchmark_value 


change 


value 


percentage 


weight 


benchmark_weight 


subcategories 


subcategory 


value 


benchmark_value 


change 


value 


percentage 


weight 
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Description 


List of spending information separated by categories and merchants. 


List of spending information separated by categories and their relative 
subcategories. 


Spending category as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given category. 


Sum of all transactions over the benchmark period for the given 
category. 


Difference in total net cash outflows per category between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all spending over the period related to this category. 


The proportion of all spending over the benchmark period related to this 
category. 


List of spending subcategory as defined in the Nucleus transactions. 


Spending category as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given subcategory. 


Sum of all transactions over the benchmark period for the given 
subcategory. 


Difference in total net cash outflows per subcategory between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all spending over the period related to this 
subcategory. 
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Field 


benchmark_weight 


by_merchant 


merchant 


value 


benchmark_value 


change 


value 


percentage 


weight 


benchmark_weight 


outliers 


income_details 


by_category 


category 


value 


benchmark_value 
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Description 


The proportion of all spending over the benchmark period related to this 
subcategory. 


List of spending information separated by merchant. 


Merchant name as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given merchant. 


Sum of all transactions over the benchmark period for the given 
merchant. 


Difference in total net cash outflows per merchant between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all spending over the period related to this merchant. 


The proportion of all spending over the benchmark period related to this 
merchant. 


List of spending transactions whose amount is beyond 2.5 median 
absolute deviations from the median of all transaction amounts. Each 
entry represent a raw transaction record from Nucleus. Please see 
Nucleus Portfolio Transaction and Aggregation Account Transaction for 
more details on underlying fields. 


List of income information separated by categories and merchants. 


List of income information separated by categories and their relative 
subcategories. 


Income category as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given category. 


Sum of all transactions over the benchmark period for the given 
category. 
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change 


value 


percentage 


weight 


benchmark_weight 


subcategories 


subcategory 


value 


benchmark_value 


change 


value 


percentage 


weight 


benchmark_weight 


by_merchant 


merchant 


value 


benchmark_value 


Hydrogen Proton API Reference 


Description 


Difference in total net cash inflows per category between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all income over the period related to this category. 


The proportion of all income over the benchmark period related to this 
category. 


List of income subcategory as defined in the Nucleus transactions. 


Income category as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given subcategory. 


Sum of all transactions over the benchmark period for the given 
subcategory. 


Difference in total net cash inflows per subcategory between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all income over the period related to this subcategory. 


The proportion of all income over the benchmark period related to this 
subcategory. 


List of income information separated by merchant. 


Merchant name as defined in the Nucleus transactions. 


Sum of all transactions over the period for the given merchant. 


Sum of all transactions over the benchmark period for the given 


merchant. 
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Field 
change 
value 
percentage 
weight 
benchmark_weight 
outliers 


NUCLEUS DATA DEPENDENCIES 


e Client 

* Account 

* Portfolio 

e Portfolio Transaction 


* Aggregation Account 
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Description 


Difference in total net cash inflows per merchant between the trend 
period and the benchmark trend period. 


Value change as of the analysis end date. 


Percentage change as of the analysis end date. 


The proportion of all income over the period related to this merchant. 


The proportion of all income over the benchmark period related to this 
merchant. 


List of income transactions whose amount is beyond 2.5 median 
absolute deviations from the median of all transaction amounts. Each 
entry represent a raw transaction record from Nucleus. Please see 
Nucleus Portfolio Transaction and Aggregation Account Transaction for 
more details on underlying fields. 


* Aggregation Account Transaction 


e Transaction Categories 


Fee Analysis 


Fee Analysis provides a detailed breakdown of the various fees paid across a client's accounts, including 


investment-related fees and banking fees. This offers insight into the size, frequency, and source of fee 


activity, as well as an opportunity to identify fee outlays that are unknown or undesirable. The analysis 


operates on transaction data stored for a given client. 


HTTP REQUEST 
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POST /fee analysis 


NAV Ill 


Example Request 
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curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


-d Éi 


"client id": "c25d94fb-ce5f-49e7-8e43-9ffd44eb7b0b", 
"start date": "2016-01-01", 

"end date": "2020-09-01", 

"currency code": "USD" 


)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/fee analysis" 


ARGUMENTS 


Parameter 


client id 


UUID, conditional requirement 


aggregation account ids 
array[UUID], conditional 


requirement 
transaction status scope 


array[string] 


currency_code 


string 


currency conversion 
string 


start date 
date 


Description 


The ID of a Nucleus Client. Conditionally required if 
aggregation account ids is not passed in the request. 


An array of ID(s) of Nucleus Aggregation Accounts. Conditionally 
required if client id is not passed in the request. 


If populated, only transactions whose status matches one of the array 
values are considered in the analysis. Defaults to nu11 , meaning all 
transactions are considered regardless of the status. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Only records with this currency code will be considered. 
Defaults to USD if currency. conversion is not provided. If 
currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Records will be converted from their original currency to the 
one indicated here. Conversions are supported both to and from the 
following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 


Currencies. 


Start date of the fee analysis. Defaults to earliest date there is data. 
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zi 
z 


Parameter Description 
end date End date of the fee analysis. Defaults to latest date there is data. 
date 


Example Response 


"analysis start": "2016-01-01", 
"analysis end": "2020-09-01", 
"currency code": "USD", 
"summary": { 
"number of accounts": 2, 
"holding fees": { 
"number of holdings": 1, 
"holding amount": 7935.25, 
"annual fee": 238.06, 
"average expense ratio": 0.03, 
"by holding": [ 


{ 
"id": "be372da6-0ccb-489e-972c-b1be44dfe0d8" , 
"ticker": "VNQ", 
"ticker name": "Vanguard Real Estate ETF", 
"shares": 100.0, 
"price": 79.35, 
"amount": 7935.25, 
"expense ratio": 0.03, 
"annual fee": 238.06 
3 


J 
"transaction_fees": { 
"number of transactions": 8, 
"latest transaction date": "2020-06-23T100:00:00.00040000", 
"total": 104.33, 
"min": 3.5, 
"max": 35.0, 
"median": 11.2, 
"mean": 13.04, 
"by category": [ 
{ 


"category": "Investment", 
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"number of transactions": 5, 
"latest transaction date": "2020-06-23T00:00:00.00040000", 
"total": 60.83, 
"min": 7.81, 
"max": 15.76, 
"median": 13.45, 
"mean": 12.17, 
"subcategories": [ 
{ 
"subcategory": "Margin Expense", 
"number of transactions": 1, 
"latest transaction date": "2019-08-02T00:00:00.000+0000", 
"total": 13.45, 
"min": 13.45, 
"max": 13.45, 
"median": 13.45, 
"mean": 13.45 


"subcategory": "Trade Commissions", 
"number of transactions": 3, 

"latest transaction date": "2020-06-03T00:00:00.000:0000", 
"total": 39.57, 

"min": 8.95, 

"max": 15.76, 

"median": 14.86, 

"mean": 13.19 


"subcategory": "Administrative Fee", 
"number of transactions": 1, 

"latest transaction date": "2020-06-23T00:00:00.00040000", 
"total": 7.81, 

"min": 7.81, 

"max": 7.81, 

"median": 7.81, 

"mean": 7.81 


"category": "Banking & Credit", 

"number of transactions": 3, 

"latest transaction date": "2020-04-16T00:00:00.000:0000", 
"total": 43.5, 

"min": 345, 
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"max": 35.0, 
"median": 5.0, 


NAV III 


"mean": 14.5, 
"subcategories": [ 


{ 
"subcategory": "Banking Fee", 
"number of transactions": 1, 
"latest transaction date": "2020-02-01T00:00:00.00040000", 
"total": 5.0, 
"min": 5.0, 
"max": 5.0, 
"median": 5.0, 
"mean": 5.0 
bo 
{ 
"subcategory": "Transfer Fee", 
"number of transactions": 1, 
"latest transaction date": "2020-03-21T00:00:00.00040000", 
"total": 3.5, 
“min”: 3.5; 
"max": 3.5, 
"median": 3.5, 
"mean": 3.5 
Jo 
{ 
"subcategory": "Overdraft Fee", 
"number of transactions": 1, 
"latest transaction date": "2020-04-16T00:00:00.00040000", 
"total": 35.0, 
"min": 35.0, 
"max": 35.0, 
"median": 35.0, 
"mean": 35.0 
} 
] 
} 
] 
} 
J 
"by account": [ 
{ 
"aggregation account id": "481cfa4e-fed0-453d-b0e0-b987aaaad459", 
"account name": "Bank Gold Investment", 
"institution name": "Citywide Bank", 


"holding fees": { 
"number of holdings": 1, 
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"holding amount": 7935.25, 

"annual fee": 238.06, 

"average expense ratio": 0.03, 

"by holding": [ 


NAV III 


{ 
"id": "be372da6-@ccb-489e-972c-b1be44dfe0d8", 
"ticker": "VNQ", 
"ticker name": "Vanguard Real Estate ETF", 
"shares": 100.0, 
"price": 79.35, 
"amount": 7935.25, 
"expense ratio": 0.03, 
"annual fee": 238.06 
} 


J 


“transaction fees": { 
"number of transactions": 5, 
"latest transaction date": "2020-06-23T00:00:00.00040000", 
"total": 60.83, 
"min": 7.81, 
"max": 15.76, 
"median": 13.45, 
"mean": 12.17, 
"by category": [ 
{ 
"category": "Investment", 
"number of transactions": 5, 
"latest transaction date": "2020-06-23T00:00:00.00040000", 
"total": 60.83, 
"min": 7.81, 
"max": 15.76, 
"median": 13.45, 
"mean": 12.17, 
"subcategories": [ 
{ 
"subcategory": "Margin Expense", 
"number of transactions": 1, 
"latest transaction date": "2019-08-02T100:00:00.000-40€ 
"total": 13.45, 
"min": 13.45, 
"max": 13.45, 
"median": 13.45, 
"mean": 13.45 


Jo 
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"subcategory": "Trade Commissions", 
"number of transactions": 3, 

"latest transaction date": "2020-06-03T100:00:00.000-«0€ 
"total": 39:57, 

"min": 8.95, 

"max": 15.76, 

"median": 14.86, 

"mean": 13.19 


NAV III 


"subcategory": "Administrative Fee", 
"number of transactions": 1, 

"latest transaction date": "2020-06-23T100:00:00.000-«0€ 
"total": 7.81, 

"min": 7.81, 

"max": 7.81, 

"median": 7.81, 

"mean": 7.81 


"aggregation account id": "ac5f3095-bcee-431f-b200-53bc74480259", 
"account name": "Bank Gold Checking", 
"institution name": "Citywide Bank", 
"holding fees": { 

"number of holdings": 0, 

"holding amount": 0, 

"annual fee": 0, 

"average expense ratio": 0, 

"by holding": [] 
bo 
"transaction fees": { 

"number of transactions": 3, 

"latest transaction date": "2020-04-16T00:00:00.00040000", 

"total": 43.5, 

"min": 3.5, 

"max": 35.0, 

"median": 5.0, 

"mean": 14.5, 

"by category": [ 

{ 
"category": "Banking & Credit", 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 321/440 


8/3/23, 5:09 PM Hydrogen Proton API Reference 
"number of transactions": 3, 

"latest transaction date": "2020-04-16T00:00:00.00040000", 
"total": 43.5, 

"min": 3.5, 

"max": 35.0, 

"median": 5.0, 


NAV III 


"mean": 14.5, 
"subcategories": [ 
{ 

"subcategory": "Banking Fee", 
"number of transactions": 1, 
"latest transaction date": "2020-02-01T100:00:00.000-«0€ 
"total": 5.0, 
"min": 5.0, 
"max": 5.0, 
"median": 5.0, 
"mean": 5.0 


"subcategory": "Transfer Fee", 
"number of transactions": 1, 

"latest transaction date": "2020-03-21T100:00:00.000-«0€ 
“total”: 3,5; 

"min": 3.5, 

"max": 3.5, 

"median": 3.5, 

"mean": 3.5 


"subcategory": "Overdraft Fee", 
"number of transactions": 1, 

"Latest transaction date": "2020-04-16T00:00:00.000-«0€ 
"total": 35.0, 

"min": 35.0, 

"max": 35.0, 

"median": 35.0, 

"mean": 35.0 
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we 


RESPONSE 


Field 


analysis_start 


analysis_end 


currency_code 


summary 


number_of_accounts 


holding_fees 


number_of_holdings 


holding amount 


annual fee 


average expense ratio 


by holding 


id 


ticker 
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Description 


Start date of the analysis. 


End date of the analysis. 


Currency code associated with monetary response values. 


Summary of fees incurred across all aggregation accounts. 


Number of aggregation accounts that incur fees. 


Holding fees incurred on Nucleus Aggregation Account 


Holdings. 


Number of holdings that incur fees. 


Total amount of holdings that incur fees. 


Total estimated annual holding fees to be incurred. 


Average expense ratio of the holdings. 


Holding fees by individual holding. 


ID of the Nucleus Aggregation Account Holding. 


Ticker of the holding. 
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= Field Description 
à 
zZ ticker_name Ticker name of the holding. 
shares Number of shares of the holding. 
price Price per share of the holding. 
amount Amount of the holding. 
expense_ratio Expense ratio of the holding. 
annual_fee Estimated annual holding fee to be incurred. 
transaction_fees Transaction fees incurred as Nucleus Aggregation Account 
Transactions. 
number_of_transactions Total number of transaction fees incurred. 
latest_transaction_date Latest date a transaction fee was incurred. 
total Total amount of fees incurred. 
min Minimum fee incurred. 
max Maximum fee incurred. 
median Median fee incurred. 
mean Average fee incurred. 
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Field 


NAV Ill 


by_category 


category 


number_of_transactions 


latest_transaction_date 


total 


min 


max 


median 


mean 


subcategories 


subcategory 


number_of_transactions 
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Description 


Transaction fees by category and subcategory. 


Category of the transactions. Value will be either Banking 
& Creditor Investment , depending on whether the fee 
was charged to a non-investment or investment 


aggregation account, respectively. 


Number of transaction fees with this category. 


Latest date a transaction fee was incurred with this 


category. 


Total amount of fees incurred with this category. 


Minimum fee incurred with this category. 


Maximum fee incurred with this category. 


Median fee incurred with this category. 


Average fee incurred with this category. 


Transaction fees by subcategory. 


Subcategory of the transactions. For Banking & Credit 
category, the subcategory will reflect the 

bank credit.subcategory value of the underlying 
transaction. For Investment category, the subcategory 
will reflect the investment.investment type value, or 
will be set to Trade Commissions for fees charged as 


part of trade-related transactions. 


Number of transaction fees with this subcategory. 
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Field 


NAV Ill 


latest_transaction_date 


total 


min 


max 


median 


mean 


by_account 


aggregation_account_id 


account_name 


institution_name 


holding fees 


number_of_holdings 


holding amount 


annual fee 


average expense ratio 
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Description 


Latest date a transaction fee was incurred with this 
subcategory. 


Total amount of fees incurred with this subcategory. 


Minimum fee incurred with this subcategory. 


Maximum fee incurred with this subcategory. 


Median fee incurred with this subcategory. 


Average fee incurred with this subcategory. 


Fees broken down by aggregation account. 


ID of the Nucleus Aggregation Account. 


Name of the aggregation account. 


Name of the institution for the aggregation account. 


Holding fees incurred on Nucleus Aggregation Account 


Holdings. 


Number of holdings that incur fees. 


Total amount of holdings that incur fees. 


Total estimated annual holding fees to be incurred. 


Average expense ratio of the holdings. 
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= Field Description 
> 
< 
z 
by holding Holding fees by individual holding. 
id ID of the Nucleus Aggregation Account Holding. 
ticker Ticker of the holding. 
ticker name Ticker name of the holding. 
shares Number of shares of the holding. 
price Price per share of the holding. 
amount Amount of the holding. 
expense ratio Expense ratio of the holding. 
annual fee Estimated annual holding fee to be incurred. 
transaction fees Transaction fees incurred as Nucleus Aggregation Account 
Transactions. 
number of transactions Total number of transaction fees incurred. 
latest transaction date Latest date a transaction fee was incurred. 
total Total amount of fees incurred. 
min Minimum fee incurred. 
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Field 


NAV Ill 


max 


median 


mean 


by_category 


category 


number_of_transactions 


latest_transaction_date 


total 


min 


max 


median 


mean 


subcategories 


subcategory 
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Description 


Maximum fee incurred. 


Median fee incurred. 


Average fee incurred. 


Transaction fees by category and subcategory. 


Category of the transactions. Value will be either Banking 


& Creditor Investment , depending on whether the fee 


was charged to a non-investment or investment 


aggregation account, respectively. 


Number of transaction fees with this category. 


Latest date a transaction fee was incurred with this 


category. 


Total amount of fees incurred with this category. 


Minimum fee incurred with this category. 


Maximum fee incurred with this category. 


Median fee incurred with this category. 


Average fee incurred with this category. 


Transaction fees by subcategory. 


Subcategory of the transactions. For Banking & Credit 
category, the subcategory will reflect the 
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Field bank_credit.subcategory value of the underlying 
transaction. For Investment category, the subcategory 


NAV Ill 


will reflect the investment.investment_type value, or 
will be set to Trade Commissions for fees charged as 
part of trade-related transactions. 


number_of_transactions Number of transaction fees with this subcategory. 


latest_transaction_date Latest date a transaction fee was incurred with this 


subcategory. 
total Total amount of fees incurred with this subcategory. 
min Minimum fee incurred with this subcategory. 
max Maximum fee incurred with this subcategory. 
median Median fee incurred with this subcategory. 
mean Average fee incurred with this subcategory. 


NUCLEUS DATA DEPENDENCIES 


* Client 

* Aggregation Account 

* Aggregation Account Transaction 
e Aggregation Account Holding 

* Security 


* Security Price 


Financial Health Check (Personal) 
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It is important to assess the health of a client's financial situation in order to provide them with 


z recommendations and guidance. This tool provides a financial health check by generating a series of financial 
Z ratios. After collecting information about the user’s assets, liabilities, income, and expenses, this tool returns 
ratio results and indicates a pass or fail based on a rule of thumb measure. The rule of thumb can be the 
system default or be overridden. 
HTTP REQUEST 
POST /financial_health_check 
Example Request 
curl -X POST -H “Authorization: Bearer <access_token>" \ 
-H "Content-Type: application/json" \ 
-d '( 
"liquid assets": 5000, 
"non liquid assets": 10000, 
"short term liabilities": 11000, 
"total liabilities": 14000, 
"gross annual income": 60000, 
"net monthly income": 3500, 
"monthly expenses": 3000, 
"ratio targets": { 
"liquidity ratio expenses": 2.5, 
"liquidity ratio liabilities": 0.1, 
"current ratio": 0.5, 
"asset allocation ratio": 1.5, 
"savings ratio gross": 0.1, 
"savings ratio net": 0.1 
} 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/financial health check" 
4 > 
ARGUMENTS 
Parameter Description 
liquid_assets Value for the sum of cash and cash equivalents, checking 
float accounts, savings accounts, money market accounts, money 


market mutual funds, CDs with short maturities, and similar 
assets. 
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Parameter 


non_liquid_assets 
float 


short_term_liabilities 


float 


total liabilities 


float 


gross annual income 


float 


net monthly income 
float 


monthly expenses 
float 


ratio targets 


map 


liquidity ratio expenses 


float 


liquidity ratio liabilities 


float 


current ratio 
float 


asset allocation ratio 


float 


Hydrogen Proton API Reference 


Description 


Value for non-money market investment accounts, vehicles, real 
estate, business interests, personal property, the cash value of 


insurance policies, and similar assets. 


Value for all debt and credit obligations, charges, bills, and 
payments due within one year. 


Value for total liabilities, examples include mortgages, car loans, 
credit card balances, and student loans. Includes 
short term liabilities. 


Total amount of income earned annually before taxes. 


Take-home monthly pay after taxes and other payroll deductions. 


Value for average monthly living expenses. 


Target values for each of the available financial ratios. These 
values are used as a benchmark for the financial health check 
and determine pass or fail. More information for these ratios can 
be found in the Appendix. 


Target ratio value for liquidity ratio expenses. Defaults to 
2.5. The ratio value is calculated as liquid assets / 
monthly expenses. 


Target ratio value for liquidity ratio liabilities. Defaults 
to 0.1. The ratio value is calculated as liquid assets / 
total liabilities. 


Target ratio value for current ratio. Defaults to 0.5. The 
ratio value is calculated as liquid assets / 


short term liabilities. 


Target ratio value for asset allocation ratio. Defaults to 
1.5. The ratio value is calculated as liquid assets / 


net worth. 
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= Parameter 

> 

x 

zZ savings_ratio_gross 
float 


savings_ratio_net 
float 


client_id 
UUID 


lookback_periods 


integer 


Example Response 


Hydrogen Proton API Reference 


Description 


Target ratio value for savings_ratio_gross . Defaults to 0.1. 
The ratio value is calculated as monthly_surplus / 


gross monthly income. 


Target ratio value for savings ratio net. Defaults to 0.1. 
The ratio value is calculated as monthly surplus / 


net monthly income. 


The ID of a Nucleus client used to derive one or more of the 
following based on the client's financials: liquid assets, 
non liquid assets, short term liabilities, 

total liabilities, net monthly income, and 

monthly expenses . If raw values for any of these optional 
parameters are not provided, we will use client id to try to 


derive those values instead. 


Number of monthly periods to analyze when deriving income and 
expense values using a client id. Values are averaged across 


all periods. Defaults to 3. 


"liquidity ratio expenses": { 
"patio result": 1.6667, 
"target value": 2.5, 
"pass": false, 
"percentile grade": 66 


D 


"liquidity ratio liabilities": 


"ratio result": 0.3571, 
"target value": 0.1, 
"pass": true, 
"percentile grade": 100 
bo 
"current ratio": { 
"ratio result": 0.4545, 
"target value": 0.5, 
"pass": false, 
"percentile grade": 90 
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D 
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"ratio result": 5, 
"target value": 1.5, 


"pass": true, 


"asset allocation ratio": 


Hydrogen Proton API Reference 


"percentile grade": 100 


J 

"savings_ratio_gross": { 
"ratio result": 0.1, 
"target value": 0.1, 
"pass": true, 


"percentile grade": 100 


D 


"savings ratio net": { 


"ratio result": 0.1429, 


"target value": 0.1, 
"pass": true, 
"percentile grade": 
bo 
"total assets": 15000, 
"net worth": 1000, 
"gross monthly income": 
"monthly surplus": 500 


RESPONSE 


Field 


liquidity ratio expenses 


ratio result 


target value 


pass 


percentile grade 


100 


5000, 


Description 


Ratio measuring available liquidity with respect to ongoing expenses. 


The ratio value, calculated as liquid assets / 
monthly expenses. 


The target ratio value, as determined by ratio targets. 


A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 
target value,then pass is true. 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 
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liquidity ratio liabilities 


ratio result 


target value 


pass 


percentile grade 


current ratio 


ratio result 


target value 


pass 


percentile grade 


asset allocation ratio 


ratio result 


target value 


pass 
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Description 


Ratio measuring available liquidity with respect to liabilities. 


The ratio value, calculated as liquid assets / 
total liabilities. 


The target ratio value, as determined by ratio targets. 


A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 


target value,then pass is true. 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 


Ratio measuring available liquidity with respect to short-term 
liabilities. 


The ratio value, calculated as liquid assets / 
short term liabilities. 


The target ratio value, as determined by ratio targets. 


A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 


target value,then pass is true. 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 


Ratio measuring available liquidity with respect to net worth. 


The ratio value, calculated as liquid assets / net worth. 


The target ratio value, as determined by ratio targets. 


A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 


target value,then pass is true. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 334/440 


8/3/23, 5:09 PM 


zi 
z 


Field 


percentile grade 


savings ratio gross 


ratio result 


target value 


pass 


percentile grade 


savings ratio net 


ratio result 


target value 


pass 


percentile grade 


total assets 


net worth 


gross monthly income 


monthly surplus 
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Description 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 


Ratio measuring savings potential with respect to gross income. 


The ratio value, calculated as monthly surplus / 


gross monthly income. 

The target ratio value, as determined by ratio targets. 

A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 


target value,then pass is true. 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 


Ratio measuring savings potential with respect to net income. 


The ratio value, calculated as monthly surplus / 
net monthly income. 


The target ratio value, as determined by ratio targets. 
A boolean indicating if ratio result is sufficiently high. If 
ratio result is greater than or equal to the corresponding 


target value,then pass is true. 


A linear percentile score for ratio result on a scale from 0 to 100, 
where 100 represents the corresponding target value. 


Total assets, calculated as liquid assets + non liquid assets. 


Net worth, calculated as total assets - total liabilities. 


Gross monthly income, calculated as gross annual income / 12. 


Net monthly surplus, calculated as net monthly income - 
monthly expenses. 
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NUCLEUS DATA DEPENDENCIES 


Client 
* Aggregation Account 


NAV Ill 


* Aggregation Account Balance 

e Aggregation Account Transaction 
e Account Categories 

e Transaction Categories 


Financial Picture 


Financial Picture considers all of a client's aggregation account information in order to provide a complete 
overview of the client's financial situation in a specified currency and over a specified date range. For all 
requests, the snapshot response provides the client's total assets, total liabilities, and net worth, along with a 
categorical breakdown of where the client's wealth is positioned. The optional history and change 
responses provide a more detailed insight into how the client's financial picture has changed over time. 


HTTP REQUEST 


POST /financial picture 


Example Request 


curl -X POST -H "Authorization: Bearer «access tokens" \ 

-H "Content-Type: application/json" \ 

-d '{ 
"client id": "a32a48f7-d30e-489b-9d2b-576a3939343f", 
"currency code": "USD", 
"start date": "2015-06-15", 
"end date": "2015-06-16", 
"show history": true, 
"show change": true, 
"show category breakdown": true, 
"create log": true 

)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/financial picture" 


ARGUMENTS 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 336/440 


8/3/23, 5:09 PM 


NAV Ill 


Parameter 


client_id 


UUID, conditional requirement 


household_id 
UUID, conditional requirement 


currency_code 


string 


currency_conversion 
string 


start_date 
date 


end_date 
date 


show_change 


boolean 


show_history 


boolean 


show_category_breakdown 


boolean 


create_log 
boolean 


Example Response 


Hydrogen Proton API Reference 


Description 


The ID of a Nucleus client whose data to analyze. Conditionally required if 
household_id is not provided. 


The ID of a Nucleus household whose data to analyze. Conditionally 
required if client_id is not provided. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Only records with this currency code will be considered. 
Defaults to USD if currency_conversion is not provided. If 
currency_conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 3 
characters. Records will be converted from their original currency to the 
one indicated here. Conversions are supported both to and from the 
following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


Start date of the financial picture analysis. Defaults to earliest date there is 
data. 


End date of the financial picture analysis. Defaults to latest date there is 
data. 


If true, return cumulative changes in the client’s total assets, total 
liabilities, and net worth over time within the specified date range. Defaults 
to false. 


If true, return a daily history of the client’s financial picture within the 
specified date range. Defaults to false. 


If true, return detailed breakdowns by category and subcategory within 
the snapshot and history objects. Defaults to true. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Nucleus as 
an audit log, and the resulting audit_log id will be returned in the 
Proton response. Defaults to false. 
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"currency code": "USD", 
"snapshot": { 
"total assets": { 
"balance": 172860.93, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
bo 
"total liabilities": { 
"balance": 56875.25, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
bo 
"net worth": { 
"balance": 115985.68, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
J 
"investable cash": { 
"balance": 90818.39, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
J 
"retirement_savings": { 
"balance": 0.0, 
"latest balance time stamp": null 


bo 
"by category": [ 
{ 
"category": "Property", 
"balance": 82042.54, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z", 
"subcategories": [ 
{ 
"subcategory": "other", 
"balance": 82042.54, 
"latest balance time stamp": "2015-06-16T00:00:00.0002" 
} 
] 
bo 
{ 
"category": "Loan", 


"balance": 56875.25, 
"latest balance time stamp": "2015-06-16100:00:00.0007", 
"subcategories": [ 
{ 
"subcategory": "Mortgage", 
"balance": 56875.25, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z2" 
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"category": "Banking", 

"balance": 90818.39, 

"latest balance time stamp": "2015-06-16T00:00:00.000Z", 
"subcategories": [ 


{ 
"subcategory": "Savings", 
"balance": 53246.2, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
bo 
{ 
"subcategory": "Checking", 
"balance": 37572.19, 
"latest balance time stamp": "2015-06-16T00:00:00.000Z" 
} 
] 
} 
] 
J 
"change": { 


"analysis start": "2015-06-15", 
"analysis end": "2015-06-16", 
"total assets": { 
"1 day": { 
"value": 0.0, 
"percentage": 0.0 


bo 
"total": { 
"value": 0.0, 
"percentage": 0.0 
} 
bo 
"total liabilities": { 
"1 day": { 
"value": 0.0, 
"percentage": 0.0 
bo 
"total": { 
"value": 9.9, 
"percentage": 0.0 
3 
bo 


"net worth": { 
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z "value": 0.0, 
= "percentage": 0.0 
bo 
"total": { 
"value": 0.0, 
"percentage": 0.0 
} 
bo 
"investable cash": { 
"1 day": { 
"value": 0.0, 
"percentage": 0.0 
bo 
"total": { 
"value": 0.0, 
"percentage": 0.0 
} 
bo 
"retirement savings": { 
"1 day": { 
"value": 0.0, 
"percentage": 0.0 
J 
"total": { 
"value": 0.0, 
"percentage": 0.0 
} 
} 
bo 
"history": | 
d 


"date": "2015-06-15", 
"total assets": 172860.93, 
"total liabilities": 56875.25, 
"net worth": 115985.68, 
"investable cash": 90818.39, 
"retirement savings": 0.0, 
"by category": [ 
{ 
"category": "Property", 
"balance": 82042.54, 
"subcategories": [ 
d 
"subcategory": "other", 
"balance": 82042.54 
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"category": "Loan", 
"balance": 56875.25, 
"subcategories": | 


{ 
"subcategory": "Mortgage", 
"balance": 56875.25 
} 
] 
bo 
{ 
"category": "Banking", 
"balance": 90818.39, 
"subcategories": [ 
{ 
"subcategory": "Savings", 
"balance": 53246.2 
bo 
{ 
"subcategory": "Checking", 
"balance": 37572.19 
} 
] 
] 
Jo 
d 


"date": "2015-06-16", 
"total assets": 172860.93, 
"total liabilities": 56875.25, 
"net worth": 115985.68, 
"investable cash": 90818.39, 
"retirement savings": 0.0, 
"by category": [ 
{ 
"category": "Property", 
"balance": 82042.54, 
"subcategories": [ 
{ 
"subcategory": "other", 
"balance": 82042.54 
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= bo 
a ( 
= "category": "Loan", 
"balance": 56875.25, 
"subcategories": [ 
{ 
"subcategory": "Mortgage", 
"balance": 56875.25 
} 
] 
J 
{ 
"category": "Banking", 
"balance": 90818.39, 
"subcategories": [ 
{ 
"subcategory": "Savings", 
"balance": 53246.2 
bo 
{ 
"subcategory": "Checking", 
"balance": 37572.19 
3 
] 
} 
] 
} 
L 
"audit log id": "6ff9c751-3745-48ec-844f-683590d8a658" 
} 
RESPONSE 
Field Description 


currency_code 


snapshot 


total assets 
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Currency code associated with monetary 
response values. 


A snapshot of the client’s financial picture as of 
the most recent available date within the date 


range. 


Total assets of the client. 
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balance 


latest balance time stamp 


total liabilities 


balance 


latest balance time stamp 


net worth 


balance 


latest balance time stamp 


retirement savings 


balance 


latest balance time stamp 


investable cash 


balance 


latest balance time stamp 
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Description 


Value of the total assets. 


Date and time of the total assets record. 


Total liabilities of the client. 


Value of the total liabilities. 


Date and time of the total liabilities record. 


Net worth of the client. 


Value of the net worth. 


Date and time of the net worth record. 


Retirement savings of the client. 


Value of the retirement savings. 


Date and time of the retirement savings record. 


Investable cash of the client. 


Value of the investable cash. 


Date and time of the investable cash record. 
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change 


ana 


ana 


(total assets, total liabilities ,net worth) 
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by_ 


category 


category 


balance 


latest balance time stamp 


subcategories 


subcategory 


balance 


latest balance time stamp 


lysis start 


lysis end 


1-day 
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Description 


List of all aggregation accounts and balances 
by category and subcategory. 


Category of the aggregation accounts. These 
accounts are dependent on the category 


field within the Nucleus Aggregation Account. 


Total balance for this category. 


Date and time of the balance record for this 
category. 


List of subcategories within the category and 
their respective balances. 


Subcategory of the aggregation accounts. 
These accounts are dependent on the 
subcategory fields within the Nucleus 
Aggregation Account. 


Total balance for this subcategory. 


Date and time of the balance record for this 


subcategory. 


Change records of the client. 


Start date of available data used in the change 


analysis. 


End date of available data used in the change 
analysis. 


A map of the below change records will be 
provided for each of the following: 

total assets, total liabilities, 
net worth, retirement savings , and 


investable cash. 


1-day change record as of the analysis end 
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value 


percentage 


7-day 


value 


percentage 


30-day 


value 


percentage 


60-day 


value 


percentage 


90-day 


value 


percentage 
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Description 


date. 


1-day value change as of the analysis end 
date. 


1-day percentage change as of the analysis 
end date. 


7-day change record as of the analysis end 
date. 


7-day value change as of the analysis end 
date. 


7-day percentage change as of the analysis 
end date. 


30-day change record as of the analysis end 
date. 


30-day value change as of the analysis end 
date. 


30-day percentage change as of the analysis 
end date. 


60-day change record as of the analysis end 
date. 


60-day value change as of the analysis end 
date. 


60-day percentage change as of the analysis 
end date. 


90-day change record as of the analysis end 
date. 


90-day value change as of the analysis end 
date. 


90-day percentage change as of the analysis 
end date. 
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z 
" 180-day 
value 
percentage 
365-day 
value 
percentage 
total 
value 
percentage 
history 
date 


total assets 


total liabilities 


net worth 
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180-day change record as of the analysis end 
date. 


180-day value change as of the analysis end 
date. 


180-day percentage change as of the analysis 
end date. 


365-day change record as of the analysis end 
date. 


365-day value change as of the analysis end 
date. 


365-day percentage change as of the analysis 
end date. 


Change record over the entire analysis date 
range. 


Total value change over the entire analysis 
date range. 


Total percentage change over the entire 
analysis date range. 


A historical record of the client’s financials for 
each date within the date range. This is an 
array of maps, with each map corresponding to 
a date and containing the following fields: 


The date of the financial picture record. 


Total assets of the client on this date. 


Total liabilities of the client on this date. 


Net worth of the client on this date. 
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Field 


retirement_savings 


investable cash 


by_category 


category 


balance 


subcategories 


subcategory 


balance 


audit_log id 


NUCLEUS DATA DEPENDENCIES 


* Household 

« Client 

* Aggregation Account 

e Aggregation Account Balance 


e Account Categories 
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Retirement savings of the client on this date. 


Investable cash of the client on this date. 


List of all aggregation accounts and balances 
on this date by category and subcategory. 


Category of the aggregation accounts. These 
accounts are dependent on the category 
field within the Nucleus Aggregation Account. 


Total balance for this category on this date. 


List of subcategories within the category and 
their respective balances on this date. 


Subcategory of the aggregation accounts. 
These accounts are dependent on the 
subcategory fields within the Nucleus 
Aggregation Account. 


Total balance for this subcategory on this date. 


The unique id of the Audit Log record created 
in Nucleus. Only returned when create_log 
= true. 
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Recurring Transaction Analysis 


Recurring Transaction Analysis combs through a client’s transaction history to automatically identify recurring 
patterns. These patterns often represent retail subscriptions and other kinds of repeated payments that a client 


makes, such as a gym membership or a content subscription. This analysis matches transactions against 


each other based on a common merchant, amount, and time interval. It also includes built-in controls to help 


capture transaction patterns that may deviate over time. The resulting output includes summary-level 


information across all recurring transactions as well an optional drill-down into each individual recurring 


transaction stream. 


HTTP REQUEST 


POST /recurring transaction_analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 


-H "Content-Type: application/json" \ 


-d '( 
"client id": "579f5984-7281-4d60-9690-20590c7ccaa7", 
"scope": "all", 
"currency code": "USD", 
"start date": "2017-01-01", 
"end date": "2020-08-15", 
"amount deviation threshold": 0.25, 
"interval deviation threshold": 5, 
"analyze transactions": true, 
"show recurring details": true 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/recurring transaction. 
d > 
ARGUMENTS 
Parameter Description 
client_id The ID of a Nucleus Client used to source transaction data for the 


UUID, conditional requirement 


given scope , when one of account_ids or 
aggregation_account_ids is not provided. Conditionally required 
if one of aggregation account ids or account ids is not 


passed in the request. 
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Parameter 


aggregation_account_ids 
array[UUID], conditional requirement 


account_ids 
array[UUID], conditional requirement 


scope 


string 


transaction status scope 


array[string] 


currency_code 


string 


currency_conversion 
string 


start_date 
date 


end_date 
date 


amount_deviation_threshold 
float 


interval deviation threshold 


integer 
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Description 


An array of ID(s) of Nucleus Aggregation Accounts to be used when 
scope is all or external. Conditionally required if one of 


client id or account ids is not passed in the request. 


An array of ID(s) of Nucleus Accounts to be used when scope is 
all or internal. Conditionally required if one of client id or 
aggregation account ids is not passed in the request. 


The scope of data to be considered. Value must be one of the 
following: all, external, internal. Defaults to all, which will 
consider both internal transactions, or Portfolio Transactions, 
and external transactions, or Aggregation Account Transactions. 


If populated, only transactions whose status matches one of the 
array values are considered in the analysis. Defaults to null, 
meaning all transactions are considered regardless of the status. 


The alphabetic currency code used to conduct the analysis, limited 
to 3 characters. Only records with this currency code will be 
considered. Defaults to USD if currency conversion is not 
provided. If currency conversion is provided, all origin 
currencies will be considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited 
to 3 characters. Records will be converted from their original 
currency to the one indicated here. Conversions are supported both 
to and from the following currency codes: USD, GBP, EUR, AUD, 
CAD, CHF. See Currencies. 


Start date of the analysis. Defaults to earliest date there is data. 


End date of the analysis. Defaults to latest date there is data. 


Allowable deviation threshold for transaction amount, measured on 
a relative percentage basis. If this value is > 0, transaction amounts 
need not be exactly the same in order to be considered recurring. 
Must be between 0.0 and 1.0, inclusive. Defaults to 0.05. 


Allowable deviation threshold for transaction interval, measured in 
days. If this value is > O, time intervals between transactions need 
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= Parameter 
a 
z 


analyze transactions 
boolean 


flag transactions 


boolean 


show recurring details 


boolean 


only cleansed 


boolean 


Example Response 


"analysis start”: 


Hydrogen Proton API Reference 


Description 


not be exactly the same in order to be considered recurring. Must 
be greater than or equal to 0. Defaults to 3. 


If true, dynamically analyze transactions. If false, only consider 
transactions that have the is recurring attribute. Defaults to 
true. 


If true, one or more Bulk Update jobs will be executed to update 
the is recurring parameter from false to true for any 
transactions identified as recurring in this analysis. Only applicable 
when analyze transactions is setto true. Defaults to false, 
meaning no transactions will be updated. 


If true, return advanced details about each recurring transaction 
stream in the analysis. Defaults to false. 


If true, only Portfolio Transactions with the is cleansed 
parameter set to true will be considered. Defaults to false. 


"2017-01-01", 


"analysis end": "2020-08-15", 


"currency code": "USD", 


"total amount spent": 969.58, 


"by merchant": [ 


"Citibike", 


"Netflix", 


"Crunch", 
13.96 


{ 
"merchant": 
"amount spent": 400.0 
Is 
{ 
"merchant": 
"amount spent": 41.97 
bo 
1 
"merchant": 
"amount spent": 
bo 
T 
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E "merchant": "Freshly", 
a "amount spent": 213.65 
= } 
L 
"by category": [ 
d 
"category": "Travel", 
"amount spent": 400.0, 
"subcategories": | 
d 
"subcategory": "Public Transportation", 
"amount spent": 400.0 
3 
] 
D 
d 
"category": "Entertainment", 
"amount spent": 41.97, 
"subcategories": [ 
{ 
"subcategory": "Streaming", 
"amount spent": 41.97 
} 
] 
D 
d 
"category": "Health & Fitness", 
"amount spent": 313.96, 
"subcategories": | 
{ 
"subcategory": "Fitness Centers & Gyms", 
"amount spent": 313.96 
} 
] 
D 
d 
"category": "Food & Dining", 
"amount spent": 213.65, 
"subcategories": | 
{ 
"subcategory": "Meal Plans", 
"amount spent": 213.65 
} 
] 
} 
L 
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NAV III 


"merchant": "Citibike", 

"category": "Travel", 

"subcategory": "Public Transportation", 

"amount": 125.0, 

"interval": 366, 

"number of transactions": 3, 

"earliest transaction date": "2017-09-26T00:00:00.00040000", 
"latest transaction date": "2019-09-29T00:00:00.00040000", 
"projected transaction date": "2020-09-29T100:00:00.000-40000" 


"merchant": "Netflix", 

"category": "Entertainment", 

"subcategory": "Streaming", 

"amount": 13.99, 

"interval": 30, 

"number of transactions": 3, 

"earliest transaction date": "2020-04-15T00:00:00.00040000", 
"latest transaction date": "2020-06-15T00:00:00.00040000", 
"projected transaction date": "2020-07-15T00:00:00.000«0000" 


"merchant": "Crunch", 

"category": "Health & Fitness", 

"subcategory": "Fitness Centers & Gyms", 

"amount": 79.25, 

"interval": 31, 

"number of transactions": 4, 

"earliest transaction date": "2019-07-08T00:00:00.00040000", 
"latest transaction date": "2019-10-09T00:00:00.00040000", 
"projected transaction date": "2019-11-09T00:00:00.000-0000" 


"merchant": "Freshly", 

"category": "Food & Dining", 

"subcategory": "Meal Plans", 

"amount": 73.12, 

"interval": 7, 

"number of transactions": 3, 

"earliest transaction date": "2020-07-01T00:00:00.00040000", 
"latest transaction date": "2020-07-15T00:00:00.000-40000", 
"projected transaction date": "2020-07-22T00:00:00.000«0000" 
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RESPONSE 


Field 


analysis_start 


analysis_end 


currency_code 


total_amount_spent 


by_merchant 


merchant 


amount_spent 


by_category 


category 


amount_spent 


subcategories 


subcategory 


amount_spent 


recurring_details 


Hydrogen Proton API Reference 


Description 


Start date of the analysis. 


End date of the analysis. 


Currency code associated with monetary response values. 


Total expenditure on recurring transactions during the analysis 
period. 


Array of recurring expenditure by merchant. 


Name of the merchant. 


Total expenditure for the merchant during the analysis period. 


Array of recurring expenditure by category. 


Name of the category. 


Total expenditure for the category during the analysis period. 


Array of recurring expenditure by subcategory. 


Name of the subcategory. 


Total expenditure for the subcategory during the analysis period. 


Array of recurring transaction details, where each entry represents 
a stream of transactions. 
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= Field Description 

a 

= merchant Name of the merchant. 
category Category of the recurring transaction. 
subcategory Subcategory of the recurring transaction. 
amount Median amount of the recurring transaction. 
interval Median number of days between each transaction. 
number_of_transactions Number of transactions in the stream. 
earliest_transaction_date Earliest recurring transaction date in the stream. 
latest transaction date Latest recurring transaction date in the stream. 


projected transaction date Projected next recurring transaction date in the stream. 


bulk update ids An array of one or more bulk ids returned from the Bulk Update 
jobs. Only returned if flag transactions issetto true. 


NUCLEUS DATA DEPENDENCIES 


e Client 

* Account 

e Portfolio 

* Portfolio Transaction 

* Aggregation Account 

e Aggregation Account Transaction 
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A detailed and configurable analysis of spending 


HTTP REQUEST 


POST /spending_analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


-d '{ 
"business_ids": [ 
"b589ad60-86ad-42a0-b4fc-4e9b1587ff8e" 
L 
"currency code": "USD", 
"scope": "all", 
"card status scope": [ 
"activated" 
L 
"transaction_status_scope": [ 
"completed", 
"pending" 
L 
"transaction category scope": [ 
"e594f949-6f92-11eb-922d-124ab2ff7f93" 
L 
"merchant scope": [ 
"0a7b62b4-54f3-4cef-afd9-c695d1d28740" 
l 


"frequency_unit": "monthly", 
"frequency": 1, 

"start date": "2021-02-01", 
"end date": "2021-04-26", 
"show by period": true, 
"show by category": true, 
"show by merchant": true, 
"only cleansed": false, 
"only active clients": false 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/spending analysis" 
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Parameter 


business ids 
array[UUID], conditional 


requirement 


household ids 
array[UUID], conditional 


requirement 


client ids 
array[UUID], conditional 


requirement 


card ids 
array[UUID], conditional 


requirement 


aggregation account ids 
array[UUID], conditional 


requirement 


account ids 
array[UUID], conditional 


requirement 


currency code 


string 


currency conversion 


string 


Hydrogen Proton API Reference 


Description 


ID(s) of the Nucleus Business(es) used to source transaction data. All 
transactions linked to each business will be considered. Conditionally 
required if one of household ids, client ids, card ids, 
aggregation account ids,or account ids is not provided. 


ID(s) of the Nucleus Household(s) used to source transaction data. All 
transactions linked to each household will be considered. Conditionally 
required if one of business ids, client ids, card ids, 


aggregation account ids,or account ids is not provided. 


ID(s) of the Nucleus Client(s) used to source transaction data. All 
transactions linked to each client will be considered. Conditionally 
required if one of business ids, household ids, card ids, 


aggregation account ids,or account ids is not provided. 


ID(s) of the Nucleus Card(s) used to source transaction data. All 
transactions linked to each card will be considered. Conditionally 
required if one of business ids, household ids, client ids, 
aggregation account ids,or account ids is not provided. 


ID(s) of the Nucleus Aggregation Account(s) used to source 
transaction data. All transactions linked to each account will be 
considered. Conditionally required if one of business ids, 
household ids, client ids, card ids,or account ids is not 


provided. 


ID(s) of the Nucleus Account(s) used to source transaction data. All 
transactions linked to each account will be considered. Conditionally 
required if one of business ids, household ids, client ids, 
card ids,or aggregation account ids is not provided. 


The alphabetic currency code used to conduct the analysis, limited to 
3 characters. Only records with this currency code will be considered. 
Defaults to USD if currency conversion is not provided. If 
currency conversion is provided, all origin currencies will be 
considered by default. See Currencies. 


The alphabetic currency code used to conduct the analysis, limited to 


3 characters. Records will be converted from their original currency to 
the one indicated here. Conversions are supported both to and from 
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Parameter 


scope 
string 


card status scope 


array[string] 


transaction status scope 


array[string] 


transaction category scope 
array[UUID] 


merchant scope 
array[UUID] 


frequency unit 


string 


frequency 
integer 


Hydrogen Proton API Reference 
Description 


the following currency codes: USD, GBP, EUR, AUD, CAD, CHF. See 
Currencies. 


The scope of data to be considered. Value must be one of the 
following: all, external, internal, or cards. Defaults to all, 
which will consider both internal transactions, or Portfolio 
Transactions, and external transactions, or Aggregation Account 
Transactions. Passing a value of cards will return a subset of 
internal data, which is only Portfolio Transactions that are linked to 
cards. Only applicable when neither card ids, account ids,or 
aggregation account ids is provided. 


If populated, only cards whose status matches one of the array 
values are considered in the analysis. Defaults to null , meaning 
transaction data from all cards are considered regardless of the 
status. Only applicable when scope is set to cards. 


If populated, only transactions whose status matches one of the 
array values are considered in the analysis. Defaults to null, 
meaning all transactions are considered regardless of the status. 


If populated, only transactions whose transaction category id 
matches one of the array values are considered in the analysis. A 
transaction category id is considered primary if it has a 
subcategory of null, meaning it represents a high-level category 
grouping. If a primary transaction category id is passed, then 
this scope will also include any transaction category ids with the 
same category value and different subcategory values. Defaults 
to null, meaning all transactions are considered regardless of the 
transaction category id. See Transaction Categories. 


If populated, only transactions whose merchant id matches one of 
the array values are considered in the analysis. Defaults to nul1, 
meaning all transactions are considered regardless of the 
merchant id. See Merchants. 


Frequency unit of the analysis. Value may be daily, weekly, bi- 
weekly, monthly, quarterly, or annually. Defaults to monthly . 


Number of frequency_unit between each period. For example, if 
the frequency unit is weekly and the frequency is 2, this 
means each period spans two weeks. Default is 1. 
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Parameter 


as of date 
date 


lookback periods 
integer 


start date 
date 


end date 
date 


show by period 


boolean 


show by category 
boolean 


show by merchant 
boolean 


only cleansed 


boolean 


only active clients 


boolean 
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Description 


Reference date of the analysis that determines the starting point of the 
lookback periods. Defaults to today's date. Not applicable if a 
start date and end date are provided. 


Number of lookback periods to analyze. Each period length is defined 
by the combination of frequency and frequency unit provided, 
beginning atthe as of date provided. For example, if 

frequency unit is monthly, frequency is 1, and 

lookback periods is 3,then the calendar month through the 

as of date, plus the previous 3 full calendar months, will be 
analyzed. Defaults to 0 , meaning that only the period containing the 
as of date is analyzed. Not applicable ifa start date and 

end date are provided. 


Start date of the analysis. Conditionally required if end date is 
passed. Passing start date and end date will override 
as of date and lookback periods. 


End date of the analysis. Conditionally required if start date is 
passed. Passing start date and end date will override 
as of date and lookback periods. 


If true, a detailed history of spending will be returned over each of 
the periods determined by frequency unit and frequency, over 
the entire analysis period determined by either as of date and 
lookback periods or start date and end date. Defaults to 
false. 


If true, return breakdowns of spending by category and subcategory. 
Defaults to false. 


If true, return breakdowns of spending by merchant. Defaults to 
false. 


If true, only Portfolio Transactions with the is cleansed parameter 
setto true will be considered. Defaults to false so that all 
transactions are considered. 


If true, only Clients with the is active parameter setto true will 
be considered. Defaults to false so that all clients are considered. 
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Example Response 


NAV III 


"analysis start": "2021-02-01", 
"analysis end": "2021-04-26", 
"currency code": "USD", 
"summary": { 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"by category": [ 
{ 
"category": "Automotive", 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0, 
"by merchant": [ 


{ 
"merchant": "Pep Boys", 
"merchant id": "0a7b62b4-54f3-A4cef-afd9-c695d1d28740", 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0 
} 
L 
"subcategories": [ 
{ 


"subcategory": "Other", 

"transaction category id": "e594f949-6f92-11eb-922d-124ab2ff71 
"number of transactions": 13, 

"amount spent": 2267.7, 

"mean transaction amount": 174.44, 

"weight": 1.0, 

"by merchant": [ 


{ 
"merchant": "Pep Boys", 
"merchant id": "0a7b62b4-54f3-A4cef-afd9-c695d1d28740", 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0 
} 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 359/440 


8/3/23, 5:09 PM Hydrogen Proton API Reference 


= ] 
a 3 
= ] 
} 
IF 
"by merchant": [ 
{ 
"merchant": "Pep Boys", 


"merchant id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740", 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0, 
"by category": [ 
{ 
"category": "Automotive", 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0, 
"subcategories": [ 
{ 
"subcategory": "Other", 
"transaction category id": "e594f949-6f92-11eb-922d-12 
"number of transactions": 13, 
"amount spent": 2267.7, 
"mean transaction amount": 174.44, 
"weight": 1.0 


D 
"by period": | 
{ 
"period start": "2021-02-01", 
"period end": "2021-02-28", 
"analysis start": "2021-02-01", 
"analysis end": "2021-02-28", 
"number of transactions": 1, 
"amount spent": 22.55, 
"mean transaction amount": 22.55, 
"by category": [ 
{ 
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"category": "Automotive", 
"number of transactions": 1, 


NAV III 


"amount spent": 22.55, 

"mean transaction amount": 22.55, 
"weight": 1.0, 

"by merchant": [ 


{ 
"merchant": "Pep Boys", 
"merchant id": "8a7b62b4-54f3-4cef-afd9-c695d1d28740", 
"number of transactions": 1, 
"amount spent": 22.55, 
"mean transaction amount": 22.55, 
"weight": 1.0 
} 
Ip 
"subcategories": [ 
{ 
"subcategory": "Other", 
"transaction category id": "e594f949-6f92-11eb-922d-124ab2 
"number of transactions": 1, 
"amount spent": 22.55, 
"mean transaction amount": 22.55, 
"weight": 1.0, 
"by merchant": [ 
{ 
"merchant": "Pep Boys", 
"merchant id": "8a7b62b4-54f3-4cef-afd9-c695d1d287 
"number of transactions": 1, 
"amount spent": 22.55, 
"mean transaction amount": 22.55, 
"weight": 1.0 
} 
] 
} 
] 
} 
L 
"by merchant": [ 
{ 
"merchant": "Pep Boys", 


"merchant id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740", 
"number of transactions": 1, 

"amount spent": 22.55, 

"mean transaction amount": 22.55, 

"weight": 1.0, 

"by category": [ 
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"category": "Automotive", 


NAV III 


"number of transactions": 1, 

"amount spent": 22.55, 

"mean transaction amount": 22.55, 

"weight": 1.0, 

"subcategories": [ 

{ 

"subcategory": "Other", 
"transaction category id": "e594f949-6f92-11eb-922 
"number of transactions": 1, 
"amount spent": 22.55, 
"mean transaction amount": 22.55, 
"weight": 1.0 


"period start": "2021-83-01", 

"period end": "2021-03-31", 

"analysis start": "2021-03-01", 

"analysis end": "2021-03-31", 

"number of transactions": 12, 

"amount spent": 2245.15, 

"mean transaction amount": 187.1, 

"by category": [ 

{ 

"category": "Automotive", 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0, 
"by merchant": [ 


{ 
"merchant": "Pep Boys", 
"merchant id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740", 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0 
} 


]; 
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= "subcategories": [ 
a { 
= "subcategory": "Other", 
"transaction category id": "e594f949-6f92-11eb-922d-124ab2 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0, 
"by merchant": [ 
{ 
"merchant": "Pep Boys", 
"merchant id": "8a7b62b4-54f3-4cef-afd9-c695d1d287 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0 
} 
] 
} 
] 
} 
Ip 
"by merchant": [ 
{ 
"merchant": "Pep Boys", 


"merchant id": "0a7b62b4-54f3-4cef-afd9-c695d1d28740", 

"number of transactions": 12, 

"amount spent": 2245.15, 

"mean transaction amount": 187.1, 

"weight": 1.0, 

"by category": [ 

{ 

"category": "Automotive", 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0, 
"subcategories": [ 


{ 
"subcategory": "Other", 
"transaction category id": "e594f949-6f92-11eb-922 
"number of transactions": 12, 
"amount spent": 2245.15, 
"mean transaction amount": 187.1, 
"weight": 1.0 
} 
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NAV Ill 
my 


"period start": "2021-04-01", 
"period end": "2021-04-30", 
"analysis start": "2021-04-01", 
"analysis end": "2021-04-26", 
"number of transactions": 0, 
"amount spent": 0, 

"mean transaction amount": 0, 
"by category": [], 

"by merchant": [] 


} 
] 
} 
RESPONSE 
Field Description 
analysis start Start date of the analysis. 
analysis end End date of the analysis. 
currency code Currency code associated with monetary response values. 
summary Summary of spending over the analysis period. 
number of transactions Number of transactions over the analysis period. 
amount spent Amount spent over the analysis period. 
mean transaction amount Average transaction amount over the analysis period. 
by category List of spending information separated by category and 


their relative subcategories. Only returned when 
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Field 


NAV Ill 


category 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_merchant 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


subcategories 
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Description 


show_by_category is setto true. 


Category as defined in the Nucleus transactions. 


Number of transactions over the analysis period for the 
given category. 


Amount spent over the analysis period for the given 
category. 


Average transaction amount over the analysis period for 
the given category. 


Proportion of spending over the analysis period related to 
this category. 


List of spending information for the category, separated by 
merchant. Only returned when show_by_merchant is set 
to true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See 
Merchants. 


Number of transactions over the analysis period for the 
given category and merchant. 


Amount spent over the analysis period for the given 
category and merchant. 


Average transaction amount over the analysis period for 
the given category and merchant. 


Proportion of spending over the analysis period related to 
this category and merchant. 


List of subcategories for the given category. 
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Field 


NAV Ill 


subcategory 


transaction_category_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_merchant 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_merchant 
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Description 


Subcategory as defined in the Nucleus transactions. 


ID of the transaction category record for the given 
category/subcategory combination. See Transaction 
Categories. 


Number of transactions over the analysis period for the 
given subcategory. 


Amount spent over the analysis period for the given 
subcategory. 


Average transaction amount over the analysis period for 
the given subcategory. 


Proportion of spending over the analysis period related to 
this subcategory. 


List of spending information for the subcategory, separated 
by merchant. Only returned when show_by_merchant is 


setto true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See 
Merchants. 


Number of transactions over the analysis period for the 
given subcategory and merchant. 


Amount spent over the analysis period for the given 
subcategory and merchant. 


Average transaction amount over the analysis period for 
the given subcategory and merchant. 


Proportion of spending over the analysis period related to 
this subcategory and merchant. 


List of spending information separated by merchant. Only 
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Field 


NAV Ill 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_category 


category 


number of transactions 


amount spent 


mean transaction amount 


weight 


subcategories 
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Description 


returned when show by merchant is set to true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See 
Merchants. 


Number of transactions over the analysis period for the 
given merchant. 


Amount spent over the analysis period for the given 
merchant. 


Average transaction amount over the analysis period for 
the given merchant. 


Proportion of spending over the analysis period related to 
this merchant. 


List of spending information for the merchant, separated by 
category and their relative subcategories. Only returned 


when show_by_category is setto true. 


Category as defined in the Nucleus transactions. 


Number of all transactions over the analysis period for the 
given merchant and category. 


Amount spent over the analysis period for the given 
merchant and category. 


Average transaction amount over the analysis period for 
the given merchant and category. 


Proportion of spending over the analysis period related to 
this merchant and category. 


List of subcategories for the given category. 
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subcategory 


transaction_category_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_period 


period start 


period end 


analysis start 


analysis end 


number of transactions 


amount spent 


mean transaction amount 
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Description 


Subcategory as defined in the Nucleus transactions. 


ID of the transaction category record for the given 
category/subcategory combination. See Transaction 
Categories 


Number of transactions over the analysis period for the 
given merchant and subcategory. 


Amount spent over the analysis period for the given 
merchant and subcategory. 


Average transaction amount over the analysis period for 
the given merchant and subcategory. 


Proportion of spending over the analysis period related to 
this merchant and subcategory. 


Historical spending data, with frequency dependent on the 


values of frequency_unit and frequency passed in the 


request. Each entry has the fields shown below. 


Start date of the period. 


End date of the period. 


Start date of the analysis period. 


End date of the analysis period. 


Number of transactions over the period. 


Amount spent over the period. 


Average transaction amount over the period. 
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NAV Ill 


by_category 


category 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_merchant 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 
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Description 


List of spending information for the merchant, separated by 
category and their relative subcategories. Only returned 
when show_by_category is setto true. 


Category as defined in the Nucleus transactions. 


Number of transactions over the period for the given 
category. 


Amount spent over the period for the given category. 


Average transaction amount over the period for the given 
category. 


Proportion of spending over the period related to this 
category. 


List of spending information for the category, separated by 
merchant. Only returned when show_by_merchant is set 
to true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See Merchants 


Number of transactions over the period for the given 


category and merchant. 


Amount spent over the period for the given category and 
merchant. 


Average transaction amount over the period for the given 
category and merchant. 


Proportion of spending over the period related to this 
category and merchant. 
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NAV Ill 


subcategories 


subcategory 


transaction_category_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_merchant 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 
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Description 


List of subcategories for the given category. 


Subcategory as defined in the Nucleus transactions. 


ID of the transaction category record for the given 
category/subcategory combination. See Transaction 
Categories. 


Number of transactions over the period for the given 
subcategory. 


Amount spent over the period for the given subcategory. 


Average transaction amount over the period for the given 
category and merchant. 


Proportion of spending over the period related to this 
category and merchant. 


List of spending information for the subcategory, separated 
by merchant. Only returned when show_by_merchant is 


setto true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See 
Merchants. 


Number of transactions over the period for the given 
subcategory and merchant. 


Amount spent over the period for the given subcategory 


and merchant. 


Average transaction amount over the period for the given 
subcategory and merchant. 


Proportion of spending over the period related to this 
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by_merchant 


merchant 


merchant_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


by_category 


category 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 
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Description 


subcategory and merchant. 


List of spending information separated by merchant. Only 


returned when show_by_merchant is setto true. 


Merchant as defined in the Nucleus transactions. 


ID of the merchant record for the merchant. See 
Merchants. 


Number of transactions over the period for the given 
merchant. 


Amount spent over the period for the given merchant. 


Average transaction amount over the period for the given 


merchant. 


Proportion of spending over the period related to this 
merchant. 


List of spending information for the merchant, separated by 
category and their relative subcategories. Only returned 


when show_by_category is setto true. 


Category as defined in the Nucleus transactions. 


Number of transactions over the period for the given 
merchant and category. 


Amount spent over the period for the given merchant and 
category. 


Average transaction amount over the period for the given 
merchant and category. 


Proportion of spending over the period related to this 
merchant and category. 
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Field 
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subcategories 


subcategory 


transaction_category_id 


number_of_transactions 


amount_spent 


mean_transaction_amount 


weight 


NUCLEUS DATA DEPENDENCIES 


* Business 

e Household 

e Client 

e Card 

* Account 

e Portfolio 

e Portfolio Transaction 

* Aggregation Account 

e Aggregation Account Transaction 
e Merchant 


* Transaction Category 
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Description 


List of subcategories for the given merchant and category. 


Subcategory as defined in the Nucleus transactions. 


ID of the transaction category record for the given 
category/subcategory combination. See Transaction 
Categories. 


Number of transactions over the period for the given 
merchant and subcategory. 


Amount spent over the period for the given merchant and 
subcategory. 


Average transaction amount over the period for the given 
merchant and subcategory. 


Proportion of spending over the period related to this 
merchant and subcategory. 


Portfolio Construction 
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This service is a scoring engine to assess the level of diversification exhibited by an investor’s portfolio. The 


score compares the portfolio volatility to the volatility 


values of the underlying portfolio holdings, in order to 


derive a score from O to 100, where O indicates no diversification and 100 indicates the maximum theoretical 


diversification level. 


HTTP REQUEST 


POST /diversification_score 


Example Request 


curl -X POST -H "Authorization: Bearer 
-H "Content-Type: application/json" \ 
-d '{ 
"portfolio_tickers": 
"XOM", 
"CMCSA", 
"AMZN", 
"GOOGL", 
"AGG" 


[ 


L 
“portfolio weights": 
0.6, 
0.1, 
0.1, 
0.1, 
0.1 


[ 


]; 


"use proxy data": false 
)' "https://[sandbox][api].hydrogen 


«access token»" \ 


platform.com/proton/v1/diversification score" 


4 
ARGUMENTS 
Parameter Description 
portfolio tickers Portfolio tickers, referencing securities defined in the Nucleus API. 
array, conditional requirement 
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portfolio weights 
array, conditional requirement 


start_date 
date 


end_date 
date 


use_proxy_data 


boolean 


market_data_source 


string 


account_id 
UUID, conditional requirement 


aggregation_account_id 


UUID, conditional requirement 


allocation_id 
UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 


UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


Portfolio weights, corresponding to portfolio tickers . Must sum to 
1.0. 


Start date used for ticker price history. Defaults to the earliest common date 
among portfolio tickers prices. 


End date used for ticker price history. Defaults to the latest common date 


among portfolio tickers prices. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

portfolio tickers and portfolio weights.lf portfolio tickers 
or portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus allocation used to derive portfolio tickers and 
portfolio weights. If portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers and 
portfolio weights. If portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive portfolio tickers and 


portfolio weights. If portfolio tickers or portfolio weights is 
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Parameter Description 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 
create log If true, a record of this Proton request URL, request body, response body, 
boolean and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit log id will be returned in the Proton 
response. Defaults to false. 
Example Response 
{ 
"portfolio standard deviation": 0.15359097006164063, 
"holdings standard deviation": { 
"AGG": 0.03539292330703836, 
"AMZN": 0.30441576222578853, 
"CMCSA": 0.1830429265788811, 
"GOOGL": 0.2389454994916491, 
"XOM": 0.20299112408344339 
bo 
"diversification score": 23 
} 
RESPONSE 
Field Description 


portfolio standard deviation 


holdings standard deviation 


diversification score 


audit log id 


NUCLEUS DATA DEPENDENCIES 


The annualized standard deviation of the overall portfolio. 


The annualized standard deviations of the individual portfolio 
holdings. 


A score from 0 to 100, in which 0 indicates no diversification and 
100 indicates the maximum theoretical diversification level. 


The unique id of the audit log record created in Electron. Only 
returned when create log = true. 
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* Security 


Security Price 


NAV Ill 


e Account 

* Portfolio 

* Portfolio Holding 

e Model 

e Model Holding 

* Allocation 

e Allocation Composition 

* Aggregation Account 

e Aggregation Account Holding 


Mean-Variance Optimization 


This service generates portfolios based on the principles of convex optimization. Securities are systematically 
weighted to maximize expected portfolio return for a given level of portfolio risk, subject to the defined 
constraints. Two outcomes can be achieved with this framework: target portfolio construction and efficient 
frontier construction. A target portfolio is a single optimal portfolio that adheres to a desired risk or return level, 


while an efficient frontier is a collection of optimal portfolios across a maximal range of risk and return levels. 


HTTP REQUEST 


POST /mvo 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 


adi tf 
"tickers": ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"], 
"min assets": 2, 
"w config": ( 
"w min major": 0.05, 
"w max major": 0.7, 
"w min minor": 0.05, 
"w max minor": 0.3, 
"cash amount": 0.03 
D 


"w asset config": { 
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"US Equities": 1.0, 
"Fixed Income": 1.0, 
"Intl Equities": 1.0, 


"EM Equities": 1.0, 
"Commodities": 1.0 


bo 


"sec types": ["major", "major", "minor", "minor", "minor", "Cash"], 


"tgt type": "risk", 

"tgt val": 0.09, 

"start date": "2015-01-01", 
"end date": "2017-01-01", 
"use proxy data": false 


)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/mvo" 


ARGUMENTS 


Parameter 


tickers 


array, required 


min assets 


integer, required 


w config 


map, required 


w asset config 


map 


Description 


A list of tickers to consider during the optimization process, referencing 
securities defined in the Nucleus API. We recommend using no more than 25 
tickers in a single optimization. Pre-screening a securities universe prior to 
calling the service will result in faster execution times as well as more 
meaningful results. 


The minimum number of portfolio assets, excluding the cash security (if 
applicable). 


Weight constraints for security types. Values that can be set are w min major, 
w max major, w min minor, w max minor, and cash amount , which 
stipulate lower and upper bounds for minor and major securities, as well as a 
constant weight for cash securities. Minimums are joined with zero to form a 
binary constraint. This means that the minimum weight of securities of each type 
may either be O (i.e. not included in the final portfolio) or the stipulated minimum. 
For example, a w min major constraint of 5% indicates that if a major 
security is chosen during the optimization, its weight must be greater than or 
equal to 5%. If, however, the security is not chosen, its weight is also allowable 
at 096. 


Weight constraints for asset classes. Stipulates a maximum weight for each 
asset class represented in tickers. If an asset class is not found, the max 
constraint defaults to 100%. 
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Parameter 


sec types 


array, required 


tgt type 


string 


tgt val 
float 


start date 


date 


end date 
date 


use proxy data 
boolean 


market data source 


string 


Example Response 


Hydrogen Proton API Reference 


Description 


A type for each security in tickers . Values may be major, minor, and 

cash. major securities are intended to be securities with more lenient weight 
thresholds. minor securities are intended to be securities with tighter weight 
thresholds. cash securities are constrained to a constant weight. major and 
minor designations interact with w config to set distinct weight constraints for 
different kinds of securities. A maximum of one security may be labelled with the 
cash type. 


The target type for a target portfolio. If specified, a target portfolio is returned. 
Value may be risk or return. Risk targets place an upper bound on the 
allowed portfolio risk, while return targets place a lower bound on the allowed 
portfolio return. If excluded, a frontier of portfolios is returned. 


The target value for a target portfolio. Corresponds to tgt type , and should 
indicate either an annualized portfolio return or an annualized portfolio standard 
deviation. If excluded, defaults to 9. 


Start date for historical prices, represented in yyyy-mm-dd format. If excluded, 
defaults to today. 


End date for historical prices, represented in yyyy-mm-dd format. If excluded, 
defaults to today. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a continuous 
price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be nucleus 
or integration. When value is nucleus , security price data is sourced from 
Nucleus Security Price. When value is integration, security price data is 
sourced from a configured Integration Market Data vendor. Defaults to 
nucleus. 


"target portfolio": { 


"securities": 


"AGG" : 
"UTI" 5 


[ 
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= "SHY" 
> 
< ] A 
= "weights": [ 
0.3345, 
0.6355, 
0.03 
lL 
"ret": 0.0413, 
"risk": 0.09 
} 
} 
RESPONSE 
Field Description 
frontier Returned if tgt_type is excluded from the request. This includes the securities, 


weights, risk and return for the series of optimal portfolios. 


target_portfolio Returned if tgt_type = risk or return . This includes the securities, weights, 


risk and return for the given portfolio. 


securities The securities in the portfolio. 

weights The weights for each of the securities in the portfolio. 
ret The return of the portfolio. 

risk The risk of the portfolio. 


NUCLEUS DATA DEPENDENCIES 


e Security 


e Security Price 


Portfolio Optimization Score 


This service assesses the relative health of a portfolio, as compared to a mean-variance optimized portfolio. 


The comparison is done on the basis of return-to-risk ratio, producing a score on a 0 to 100 scale, in which 
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100 represents the optimized portfolio. A portfolio optimization score defines how far a portfolio is away from 
the mean-variance efficient frontier in order to identify any improvement potential. 


NAV Ill 


HTTP REQUEST 


POST /portfolio optimization score 


Example Request 


curl -X POST -H "Authorization: Bearer «access token5" \ 
-H "Content-Type: application/json" ^ 
A a 
"portfolio tickers": ["AGG", "AAPL", "CHTR", "PFE", "NVDA"], 
"portfolio weights": [0.1, 0.1, 0.1, 0.6, 0.1], 
"opt config": { 
"tickers": ["AGG", "AAPL", "CHTR", "PFE", "NVDA"], 
"min assets": 5, 
"w asset config": ( 
"US Equities": 1.0, 
"Fixed Income": 1.0 
bo 
"w config": { 
"w min major": 0.05, 
"w max major": 1.0, 
"w min minor": 0.05, 
"w max minor": 1.0, 
"cash amount": 0.0 
bo 
"sec types": ["minor", "minor", "minor", "minor", "minor"], 
"start date": "2016-01-01", 
"end date": "2017-01-01" 
bo 
"use proxy data": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/portfolio optimization s 


ARGUMENTS 


Parameter Description 


portfolio tickers Portfolio tickers, referencing securities defined in the Nucleus API. 


array, required 
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NAV Ill 


portfolio weights 


array, required 


tgt_type 
string 


opt_config 
map 


tickers 


array 


min_assets 


integer 


w_asset_config 


map 


w_config 
map 


w min major 
float 


w max major 
float 


w min minor 


float 


w max minor 
float 


cash amount 
float 


sec types 


array 


Hydrogen Proton API Reference 


Description 


Portfolio weights, corresponding to portfolio tickers . Must sum to 
1.0. 


The type of optimization to perform. Value may be risk or return.A 
risk optimization targets the risk of the current portfolio and attempts to 
maximize the return, while a return optimization targets the return of the 
current portfolio and attempts to minimize the risk. Defaults to return. 
Settings for portfolio optimization. Includes the fields shown below. 
Security tickers to consider during the optimization process. Defaults to 


portfolio tickers. 


Minimum number of assets included in the optimized portfolio. Defaults to 
T: 


Weight constraints for asset classes. Stipulates a maximum weight for the 


asset classes represented in tickers . If an asset class is represented in 


tickers but not found in w asset config, the weight for that asset 


class will not be constrained. 


Weight constraints for security types, includes the fields shown below. 


Minimum weight for “major” securities. Defaults to 0.05. 


Maximum weight for "major" securities. Defaults to 1. 


Minimum weight for “minor” securities. Defaults to 8.05. 


Maximum weight for "minor" securities. Defaults to 1. 


Constant weight for "cash" securities. Defaults to 8. 


Security types, corresponding to tickers. May be major, minor, or cash. 


Defaults to minor forall tickers. 
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Parameter 


start date 
date 


end date 
date 


use proxy data 


boolean 


market data source 


string 


account id 


UUID, conditional requirement 


aggregation account id 


UUID, conditional requirement 


allocation id 
UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


Start date used for ticker price history. Defaults to earliest common date 
among tickers prices. 


End date used for ticker price history. Defaults to latest common date 
among tickers prices. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive portfolio tickers and 
portfolio weights. If portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

portfolio tickers and portfolio weights.lf portfolio tickers 
or portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus allocation used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers and 
portfolio weights. If portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 
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> 

4 

zZ create_log 
boolean 


Description 


If true , a record of this Proton request URL, request body, response body, 
and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit_log_id will be returned in the Proton 


Hydrogen Proton API Reference 


response. Defaults to false. 


Example Response 


"current portfolio": { 


"tickers": [ 


L 


"AGG", 
"AAPL", 
"CHTR", 
“PFE”; 
"NVDA" 


"weights": [ 


L 


0.1, 
0.1, 
0.1, 
0.6, 
0.1 


"return": 0.2413, 
"risk": 0.1465 


bo 


"optimized portfolio": { 


"tickers": [ 


L 


"AAPL", 
“CHIR”: 
"PFE", 
"NVDA", 
"AGG" 


"weights": [ 


0.05, 
0.05, 
0.05, 
0.0745, 
0.7755 
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]; 
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a "return": 0.2413, 
= "risk": 0.0534 
bo 
"optimization score": 36.9 
} 
RESPONSE 
Field 


current portfolio 


tickers 


weights 


return 


risk 


optimized portfolio 


tickers 


weights 


return 


risk 


optimization score 


audit log id 


Description 


Details on the current portfolio. Includes the fields shown below. 


Tickers in the portfolio. 


Weights in the current portfolio, corresponding to tickers. 


The annualized mean return 


The annualized standard deviation of returns. 


Details on the optimized portfolio. Includes the fields shown below. 


Tickers in the portfolio. 


Weights in the current portfolio, corresponding to tickers. 


The annualized mean return 


The annualized standard deviation of returns. 


A score from 0 to 100 indicating the relative health of the current portfolio, 100 
being the most optimal. 


The unique id of the audit log record created in Electron. Only returned when 


create log = true. 


NUCLEUS DATA DEPENDENCIES 


* Security 

* Security Price 

* Account 

* Portfolio 

e Portfolio Holding 
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« Allocation 


NAV Ill 


e Allocation Composition 
* Aggregation Account 
* Aggregation Account Holding 


e 
Only one of account id, aggregation account id, allocation id, model id,and portfolio id 
should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Portfolio Management 


Rebalancing Signal 


This service generates trade signals to strategically rebalance a model portfolio, with support for three types of 
rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates a 
signal at the beginning of each time period with a pre-defined frequency. Drift-based rebalancing generates a 
signal whenever a portfolio holding deviates from its strategic target by a pre-defined amount. Downside 
Protection generates signals based on the observed risk of portfolio holdings, reducing exposure in stages as 
risk increases and restoring exposure in stages as risk decreases. 


HTTP REQUEST 


POST /rebalancing signal 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '( 
"model id": "a83fd921-11ab-4003-a340-9bca9d3e01bd", 
"start date": "2016-12-01", 
"end date": "2017-12-08", 
"initial weights": ( 
"CMCSA": 0.05, 
"ATRX": 0.05, 
"KO": 0.05, 
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"AMZN": 0.05, 
"GOOGL": 0.1, 
"CSCO": 0.1, 
"AGG": 0.1, 
"XOM": 0.1, 
"INTC": 0,1, 
"KHC": 0.1, 
"MCD": 0.1, 
"WMT": 0.1 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/rebalancing signal" 


ARGUMENTS 


Parameter 


model id 
UUID, required 


start date 
date, required 


end date 


date, required 


initial weights 


map 


Description 


Identifier of the model in the Nucleus API to rebalance. In order to perform 
rebalancing, downside, drift rebal or period rebal must be set in the 
Nucleus endpoint /model.The drift factor from /model holding is used as 
ofthe start date throughout the full simulation. If no drift factor is set in 

/model holding,the default drift factor from /model is used. If 

period rebal,set rebalance_period. If drift rebal, set 


default drift factor. If downside, set safe sec and cash sec. 


Start date for analysis, represented in yyyy-mm-dd format 


End date for analysis, represented in yyyy-mm-dd format 


Initial weights for model holdings. If excluded, defaults to the model's 
strategic weight from /model holding as ofthe start date. 


Example Response 


"rebalance signals": [ 


p 
H 
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= "amount": 12.745833518909741, 
a "type": 2 
= D 
d 
"date": "2017-03-28T00:00:00", 
“ticker": "^IRX', 
"signal": "BUY", 
"amount": 155.94057228998332, 
"type": 2 
D 
d 
"date": "2017-03-28T00:00:00", 
"ticker": "Ko", 
"signal": "SELL", 
"amount": 12.63570207140365, 
"type": 2 
D 
d 
"date": "2017-03-28T00:00:00", 
"ticker": "AMZN", 
"signal": "SELL", 
"amount": 16.0155517951892, 
"type": 2 
bo 
{ 
"date": "2017-03-28T00:00:00", 
"ticker": "GOOGL", 
"signal": "SELL", 
"amount": 18.65995935855528, 
"type": 2 
D 
{ 
"date": "2017-03-28T00:00:00", 
"ticker": "CSCO", 
"signal": "SELL", 
"amount": 15.988445088739898, 
"type": 2 
D 
d 
"date": "2017-03-28T00:00:00", 
"ticker": "AGG", 
"signal": "SELL", 
"amount": 45.96572996834058, 
"type": 2 
bo 
{ 
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2 "ticker": "XOM", 
= "signal": "SELL", 
"amount": 3.144146724151982, 
"type": 2 
bo 
{ 
"date": "2017-03-28T00:00:00", 
"ticker": "INTC", 
"signal": "SELL", 
"amount": 5.25300352775003, 
"type": 2 
bo 
{ 
"date": "2017-03-28T00:00:00", 
"ticker": "MCD", 
"signal": "SELL", 
"amount": 12.879881718355065, 
"type": 2 
bo 
{ 
"date": "2017-03-28T00:00:00", 
"ticker": "WMT", 
"signal": "SELL", 
"amount": 12.65231851858788, 
"type": 2 
} 
] 
} 
RESPONSE 
Field Description 


rebalance signals The rebalancing signals for the specified model. 


date The date of the given rebalancing signal. 

ticker The unique identifier of a given security. 

signal The trade action, either BUY or SELL. 

amount The amount of the trade as a percentage. For example, amount = 0.02 
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= Field Description 
> 
= translates to selling 2% of a given ticker. 
type The type of trade signal. 1 = period-based, 2 = drift-based, and 4 = downside 
protection. 


NUCLEUS DATA DEPENDENCIES 


e Model 
« Model Holding 
e Security 


e Security Price 


Order Rebalance 


Create order records necessary to rebalance an account or portfolio to its target. For an account, this endpoint 
will create order records necessary to rebalance all its portfolios according to the allocation(s) to which the 
account subscribes and models to which the portfolios subscribe. For a portfolio, this endpoint will create order 
records necessary to rebalance it to the model to which it subscribes. This rebalancing will generate orders for 
the buying of securities, selling of securities, or both. 


The endpoint returns a series of order id records and their underlying information, similar to the GET 
/order endpoint. All of the order ids will be part of a bulk order and will have a bulk order id assigned 
to them. Note that this endpoint requires any corresponding portfolio(s) and model(s) to have asset size and 
holding records. 


HTTP REQUEST 


POST /order rebalance 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"portfolio id": "ef93ce1c-b50e-4856-803a-db5332be93b0", 
"order scope": "all", 
"buy transaction code id": "f5af397b-7d22-433f-b01e-8202184a6386", 
"sell transaction code id": "7d8d41d0-ed4b-4ae2-acb3-eO0baed2ff1cc", 
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"buy threshold": 100, 
"cash sec id": "5276c9a5-5263-4aea-8027-327003738cef", 


false, 


true, 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/order rebalance" 


"commit orders": 
"non fractional": true, 
"port threshold": 100, 
"restrictions on": false, 
"sell threshold": 100, 
"use cash available": 
"use strategic": false 
ARGUMENTS 


Parameter 


portfolio id 


UUID, conditional requirement 


account id 


UUID, conditional requirement 


order scope 


string, required 


buy transaction code id 
UUID, conditional requirement 


sell transaction code id 
UUID, conditional requirement 


buy threshold 
float 


cash portfolio id 
UUID 


cash sec id 
UUID 


commit orders 
boolean 


Description 


The ID of the Nucleus Portfolio to rebalance. One of portfolio id or 


account id is required. 


The ID of the Nucleus Account to rebalance. One of portfolio id or 


account id is required. 


Value may be all, buy only,or sell only. 


The ID of the transaction code to denote a buy transaction. Conditionally 
required when order scope = all or buy only. 
The ID of the transaction code to denote a sell transaction. Conditionally 
required when order scope = all or sell only. 
Buying threshold for the account as the number of shares. Defaults to 0 . 


Only applicable when order scope = all or buy only. 


The ID of the cash portfolio for the account. Only applicable when an 


account id is provided and order scope = all or buy only. 


The ID of the cash security for the portfolio. Only applicable when a 


portfolio id is provided and order scope = all or buy only. 


Indicates if the orders should be committed for execution. Defaults to 
true which indicates they should be committed. 
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= Parameter Description 

z 

= non_fractional Indicates if purchasing/selling fractional shares of securities is allowed. 
boolean Defaults to false which indicates it is allowed. 
port_threshold Threshold for the minimum asset size of the portfolio as a monetary 
float amount for rebalancing to take place. Defaults to @. 
restrictions_on Indicates if there are restrictions on the account that should be followed. 
boolean Defaults to false which indicates there are not. 
sell_threshold Selling threshold for the account as the number of shares. Defaults to @. 
float 
use_cash_available Indicates if only the cash in the cash portfolio should be used. Defaults to 
boolean false which indicates it should not. Only applicable when 


order_scope = all or buy_only. 


use strategic Indicates if the account should be synced to strategic weights as 
boolean opposed to current weights. Defaults to false which indicates it should 
not. 


Example Response 


d 
"id": "2fae86f5-a2ab-4d11-be1d-4ce08F903135", 
"create date": "2018-02-07119:29:37.000+0000", 
"transaction code id": "7d8d41d0-ed4b-4ae2-acb3-e@baed2fficc", 
"date": "2018-02-07", 
"price": 51.25, 
"is read": true, 
"quantity": 26, 
"security id": "52654829-e80b-4f16-9f8b-c9fde8a1aa63", 
"portfolio id": "ef93ce1c-b50e-4856-803a-db5332be93b0" , 
"account id": "cce4cb18-9a0a-499e-be38-cfb089ba1781", 
"model id": "ca74f042-eb32-4965-84c6-b0754d2115c5", 
"metadata": {} 

} 
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RESPONSE 


Field 


id 


create_date 


transaction_code_id 


date 


price 


is read 


quantity 


security_id 


account_id 


portfolio id 


model id 


metadata 


Description 


The ID of the order. 


Hydrogen Proton API Reference 


The create date of the order. 


The ID of the transaction code associated with the order. 


The date of the order. 


The price of the security associated with the order. 


Indicates whether the order has been read. A value of true indicates that it 


has been read. 


The quantity of securities associated with the order. 


The ID of the security associated with the order. 


The ID of the account associated with the order. 


The ID of the portfolio associated with the order. 


The ID of the model associated with the order. 


The metadata associated with the order. 


NUCLEUS DATA DEPENDENCIES 


* Account 

* Account Allocation 
« Allocation 

e Model 

e Model Holding 

* Portfolio 

e Portfolio Holding 
* Security 

« Security Price 


e Transaction Code 
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Risk Scoring 


NAV Ill 


Risk Score 


This service calculates a risk score based on numerical answers to questions that evaluate risk appetite. The 
returned score is normalized on a scale from 0 to 100, where 0 indicates minimum risk appetite and 100 


indicates maximum risk appetite. 


HTTP REQUEST 


POST /risk_score 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"answers": [10, 400, 3, 9], 
"max answers": [10, 1000, 4, 10], 
"weights": [0.25, 0.25, 0.25, 0.25] 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/risk score" 


ARGUMENTS 

Parameter Description 

answers Answer values. Values must be greater than or equal to zero. Higher answer 

array, conditional values are assumed to indicate more appetite for risk. 

requirement 

max answers Maximum possible answer values. Values must be greater than or equal to zero. 

array, required Scales for answers and max answers need not be consistent, as values are 
automatically normalized. 

weights Weights for each answer. If sum is not 1, values are normalized proportionally. 

array Example: [60, 80, 68] would be normalized to [0.3, 8.4, 0.3]. If 
excluded, answer values are equal-weighted. 

client id The ID of the Nucleus client used to derive answers and weights. If required 

UUID, conditional parameter answers is not provided, client id and questionnaire id are 
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= Parameter Description 
> 
3 requirement both required. If raw values for optional parameter weights are not provided, we 
will use client id and questionnaire id to try to derive these values 
instead. 
questionnaire id The ID of a Nucleus questionnaire used to derive answers and weights. If 
UUID, conditional required parameter answers is not provided, client id and 
requirement questionnaire id are both required. If raw values for optional parameter 
weights are not provided, we will use client id and questionnaire id to 
try to derive these values instead. 
post score If true, a record of this client's risk score will be stored in Nucleus as a score, 
boolean and the resulting score id will be returned in the Proton response. A 
client id must be provided to post a score. Defaults to false. 
Example Response 
{ 
"risk_score": 76 
} 
RESPONSE 
Field Description 


risk score  Arisk score from 0 to 100. 


score_id The unique id of the score record created in Nucleus. Only returned when post_score = 
true anda client id is provided. 


NUCLEUS DATA DEPENDENCIES 


e Client 
e Client Response 


« Questionnaire 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 394/440 


8/3/23, 5:09 PM Hydrogen Proton API Reference 


Dimensional Risk Score 
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This service calculates a risk score based on numerical answers to questions that evaluate risk appetite 
across multiple dimensions. Multi-dimensional analysis offers a more robust way to assess risk, as responses 
can be both strategically weighted and mapped to one or more distinct risk dimensions that are also 
strategically weighted. The returned score is normalized on a scale from 0 to 100, where 0 indicates minimum 
risk appetite and 100 indicates maximum risk appetite. 


HTTP REQUEST 


POST /dimensional_risk_score 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 

-H "Content-Type: application/json" \ 

-d '{ 
"answers": [10, 400, 3, 9], 
"max answers": [10, 1000, 4, 10], 
"answer dims": [["dim1"], ["dim2"], ["dim3"], ["dim4"]], 
"dims": ["dimi", "dim2", "dim3", "dim4"], 
"dim weights": [0.25, 0.25, 0.25, 0.25], 
"answer weights": [0.25, 0.25, 0.25, 0.25] 

)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/dimensional risk score 


4 > 

ARGUMENTS 

Parameter Description 

answers Answer values. Values must be greater than or equal to zero. Higher answer 

array, conditional values are assumed to indicate more appetite for risk. 

requirement 

max answers Maximum possible answer values. Values must be greater than or equal to zero. 

array, required Scales for answers and max answers need not be consistent, as values are 


automatically normalized. 


answer dims Question risk dimensions. Maps individual answers to one or multiple risk 
array, required dimensions. Should only include labels found in dims . 
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Parameter 


dims 


array, required 


dim weights 


array 


answer weights 


array 


client id 
UUID, conditional 


requirement 


questionnaire id 
UUID, conditional 


requirement 


post score 


boolean 


Example Response 


"risk score": 
"dim scores": 
"dimi": 


Hydrogen Proton API Reference 


Description 


Labels for available risk dimensions. Each item should be a string and can be 
custom configured to reflect any number of dimensions. When more than one 
question maps to a given dimension, relationships between various 

answer weights serve as the basis for weighting answers within that 
dimension. 


Weights for each risk dimension. Values correspond to and should match the 
length of dims . If sum is not 1, values are normalized proportionally. Example: 
[60, 80, 60] would be normalized to [0.3, 0.4, 0.3]. If excluded, 
dimensions are equal-weighted. 


Weights for each risk dimension answer. If sum is not 1, values are normalized 
proportionally. Example: [60, 80, 68] would be normalized to [0.3, 0.4, 
0.3] . If excluded, answer values are equal-weighted. 


The ID of the Nucleus client used to derive answers and answer weights . If 
required parameter answers is not provided, client id and 
questionnaire id are both required. If raw values for optional parameter 
answer weights are not provided, we will use client id and 
questionnaire id to try to derive these values instead. 


The ID of a Nucleus questionnaire used to derive answers and 

answer weights . If required parameter answers is not provided, client id 
and questionnaire id are both required. If raw values for optional parameter 
answer weights are not provided, we will use client id and 
questionnaire id to try to derive these values instead. 


If true , a record of this client's risk score will be stored in Nucleus as a score, 
and the resulting score id will be returned in the Proton response. A 
client id must be provided to post a score. Defaults to false. 


76, 


{ 


100, 


"dim2": 40, 


"dim3": 


75, 
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= "dima": 90 
a } 
= } 
RESPONSE 
Field Description 


risk score. Amulti-dimensional risk score from O to 100. 
dim scores A score from 0 to 100 for each dimension that was evaluated. 


score_id The unique id of the score record created in Nucleus. Only returned when post_score = 
true anda client_id is provided. 


NUCLEUS DATA DEPENDENCIES 


e Client 
* Client Response 
e Questionnaire 


Risk Allocation 


This service returns a portfolio based on an investor's risk score, drawing from a universe of pre-defined 
allocations ora dynamically generated efficient frontier. The risk score is used to conduct a percentile 
analysis within the portfolio universe; a risk score of 0 maps to the lowest risk portfolio within the universe, 
while a risk score of 100 maps to the highest risk portfolio within the universe. The user is matched to the most 
suitable allocation, given its standard deviation and the user's risk score. 


HTTP REQUEST 


POST /risk allocation 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
sg] 
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"risk score": 49, 
"allocation method": "create", 


NAV Ill 


"opt config": 
{ 
"tickers": ["VTI", "AGG", "EFA", "VWO", "GLD", "SHY"], 
"min assets": 1, 
"w config": ( 
"w min major": 0.05, 
"w max major": 1, 
"w min minor": 0.05, 
"w max minor": 1, 
"cash amount": 0.03 
J 
"w_asset_config": { 
"US Equities": 1.0, 
"Fixed Income": 1.0, 
"Intl Equities": 1.0, 
"EM Equities": 1.0, 
"Commodities": 1.0 
ig 
"sec types": ["major", "major", "minor", "minor", "minor", "Cash"], 
"start date": "2016-01-01", 
"end date": "2017-01-01" 


bo 


"allocations": ["347b1a30-342f-41f0-b484-78c350fc4243", "7688625f-ca41-47bd-a4 


"use proxy data": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/risk allocation" 


ARGUMENTS 

Parameter Description 

risk score A risk score from 0 to 100. Defaults to 50 if not provided and not derived via 

integer client id. 

allocation method The allocation universe resource. Value may be either create or select. 

string, required create derives an allocation universe from a dynamically generated efficient 
frontier, based on opt config. select derives an allocation universe from 
pre-defined allocations, as stipulated by the identifiers found in allocations. 

opt config Portfolio optimization configuration, required if allocation method = create. 

map, conditional Information in opt config refers to security data, which must be created in 

requirement 
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Parameter 


tickers 


array, required 


min assets 


integer, required 


w config 


map, required 


w asset config 


map 


sec types 


array, required 


start date 
date 


end date 
date 


allocations 
array[UUID] 


use proxy data 
boolean 


Hydrogen Proton API Reference 


Description 


advance using the Nucleus endpoint POST /security. opt config includes 
the following parameters: 


A list of symbols for securities included in the portfolio. We recommend using no 
more than 25 tickers in a single optimization. Pre-screening a securities 
universe prior to calling the service will result in faster execution times as well as 


more meaningful results. 


The minimum number of portfolio assets, excluding the cash security (if 
applicable). 


Weight constraints for security types. Values that can be set are w min major, 
w max major, w min minor, w max minor, and cash amount , which 
stipulate lower and upper bounds for minor and major securities, as well as a 
constant weight for cash securities. Minimums are joined with zero to form a 
binary constraint. This means that the minimum weight of securities of each type 
may either be O (i.e. not included in the final portfolio) or the stipulated minimum. 
For example, a w min major constraint of 5% indicates that if a “major” 
security is chosen during the optimization, its weight must be greater than or 
equal to 596. If, however, the security is not chosen, its weight is also allowable 
at 0%. 


Weight constraints for asset classes. Stipulates a maximum weight for each 
asset class represented in tickers. If an asset class is not found, the max 
constraint defaults to 100%. 


A type for each security. Values may be major, minor,and cash. major and 
minor designations interact with w config to set distinct weight constraints 
for different kinds of securities. A maximum of one security may be defined as 


cash. 


Start date for historical prices, represented in yyyy-mm-dd format. 


End date for historical prices, represented in yyyy-mm-dd format. 


List of allocation ids in the Nucleus API to select from. As a pre-requisite, 
must have values for the performance and volatility arguments within the 
chosen allocation id. Defaults to include all available allocations. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a continuous 
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NAV Ill 


market_data_source 


string 


client_id 
UUID 


Hydrogen Proton API Reference 


Peéesctistion Defaults to false. 


Source of security price data to be used in the analysis. Value may be nucleus 


or integration. When value is nucleus , security price data is sourced from 


Nucleus Security Price. When value is integration, security price data is 


sourced from a configured Integration Market Data vendor. Defaults to 


nucleus. 


The ID of the Nucleus client used to derive risk score if risk score is not 


provided. 


Example Response 


a 


"securities": [ 
"AGG 1 5 
"VTI " 


"risk": 


ny 


RESPONSE 


Field 


securities 


weights 


id 


ret 


: 0.061, 


0.0627 


Description 


If allocation method 


the allocation created. 


If allocation method 


the allocation created. 


If allocation method 


create , the tickers of the securities that should be included in 


create , the weights of each security that should be included in 


select, the id of the allocation assigned to the client. 


The annualized return of the portfolio. 
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Field Description 


NAV Ill 


risk The annualized standard deviation of the portfolio. 


NUCLEUS DATA DEPENDENCIES 


* Security ; required if allocation method = create 

e Security Price; required if allocation_method = create 

e Allocation; performance and volatility must be set when allocation method = select 
* Allocation Composition 

* Model 

* Model Holding 

« Client 


e Score 


Simulations 


Event Study 


When clients are weighing their options between portfolios, they can run a simulation to see how the portfolio 
would have performed during key historical events. This will help them understand a portfolio's exposure to 
various financial climates. The resulting performance and risk statistics can serve as a basis to evaluate a 
portfolio in the context of a given event. 


The events parameter accepts the following event labels, each corresponding to a particular date range: 


e dot com bubble: (5/14/2001 - 9/30/2002) 

e 2008 financial crisis : (10/8/2007 - 03/02/2009) 

e brexit : (6/23/2016 - 6/27/2016) 

e 2011 black monday: (7/21/2011 - 8/10/2011) 

e September eleventh : (9/10/2001 - 9/21/2001) 

e 1987 black monday: (10/5/1987 - 10/19/1987) 

e 1992 black wednesday : (9/14/1992 - 10/9/1992) 

e 1997 asian financial crisis: (10/21/1997 - 10/27/1997) 


HTTP REQUEST 


POST /event study 
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Example Request 


Hydrogen Proton API Reference 


curl -X POST -H "Authorization: Bearer «access token5" \ 
-H "Content-Type: application/json" \ 


-d "X 


"portfolio tickers": [ 


"CVX", 

"PFE", 

"JNJ" 
]; 


"portfolio weights": [ 


0.3, 
0.4, 
0.3 

]; 


"events": [ 


"2008 financial crisis" 


]; 


"use proxy data": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/event study" 


ARGUMENTS 


Parameter 


portfolio tickers 


array, conditional requirement 


portfolio weights 


array, conditional requirement 


events 


array 


use proxy data 


boolean 


market data source 


string 


Description 


Portfolio tickers, referencing securities defined in the Nucleus API. 


Portfolio weights, corresponding to portfolio tickers. Must sum to 
1.0. 


Historical events to analyze. Each item must be one of: dot com bubble, 
2008 financial crisis, brexit, 2011 black monday, 

september eleventh, 1987 black monday, 1992 black wednesday, 
1997 asian financial crisis. Defaults to all available events. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
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Parameter 


account id 
UUID, conditional requirement 


aggregation account id 
UUID, conditional requirement 


allocation id 
UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


create log 


boolean 


Example Response 


"event summary": 


{ 


[ 


Hydrogen Proton API Reference 


Description 


sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 


vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

portfolio tickers and portfolio weights.lf portfolio tickers 
or portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus allocation used to derive portfolio tickers and 
portfolio weights. If portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


If true, a record of this Proton request URL, request body, response body, 
and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit log id willbe returned in the Proton 
response. Defaults to false. 
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E "event name": "2008 financial crisis", 
a "stats": { 
z "cumulative return": -0.4068333255300416, 
"annualized return": -0.310936012869381, 
"annualized volatility": 0.3384477617390186 
} 
} 
] 
} 
RESPONSE 
Field Description 
event_summary Summary statistics for the events analyzed. Each underlying object 
contains the fields shown below. 
event_name Label for the event, as provided in events. 
stats Portfolio statistics for the duration of the event indicated by 
event_name. 
cumlative return Cumulative return over the event duration. 
annualized return Annualized return over the event duration. 
annualized volatility Annualized standard deviation over the event duration. 
audit log id The unique id of the audit log record created in Electron. Only 


returned when create log = true. 


NUCLEUS DATA DEPENDENCIES 


* Security 

* Security Price 

* Account 

e Portfolio 

e Portfolio Holding 
* Model 
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e Model Holding 
e Allocation 


NAV Ill 


« Allocation Composition 
* Aggregation Account 


* Aggregation Account Holding 


e 

This service depends upon Security Prices for the date ranges that correspond to events in order to run 
successfully. A given event will only be anlayzed if ALL Securities indicated by portfolio tickers, 
account id, aggregation account id, allocation id, model id,or portfolio id have the 


appropriate price data. 


e 
Only one of account id, aggregation account id, allocation id, model id,and portfolio id 


should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Model Backtest 


This service simulates the behavior of a model over a specific date range in the past. It supports three types of 
model rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates 
a signal at the beginning of each time period with pre-defined frequency. Drift-based rebalancing generates a 
signal whenever a model holding deviates from its strategic target by a pre-defined amount. Downside 
Protection generates signals based on the observed risk of model holdings, reducing exposure in stages as 
risk increases and restoring exposure in stages as risk decreases. These rebalancing types can be assigned 
to a model in the Nucleus API Model Service. 


HTTP REQUEST 


POST /backtest 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '{ 
"model id": "9aad12e8-25dc-421d-a041-1b157fff7738", 
"start date": "2016-12-01", 
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"end date": "2016-12-05", 
"initial weights": { 
"GOOGL": 0.25, 
"CSCO": 0.25, 
"MCD": 0.25, 
"WMT": 0.25 
) 


"asset size": 


NAV Ill 


1000, 
"asset sizes": true, 
"trades": true, 
"holdings": true, 
"stats": 


)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/backtest" 


true 


ARGUMENTS 


Parameter 


model id 
UUID, required 


start date 
date, required 


end date 


date, required 


initial weights 


map 


asset size 
float 


asset sizes 


boolean 


trades 


boolean 


Description 


Identifier of the model in the Nucleus API to backtest. In order to perform the 
backtest, downside, drift rebal or period rebal must be set in the Nucleus 
endpoint /model. The drift factor from /model holding is used as of the 
start date throughout the full simulation. If no drift factor is set in 

/model holding,the default drift factor from /model is used. If 

period rebal,set rebalance_period. If drift rebal, set 


default drift factor. If downside, set safe sec and cash sec. 


Start date for analysis, represented in yyyy-mm-dd format. 


End date for analysis, represented in yyyy-mm-dd format. 


Initial weights for model holdings. If excluded, defaults to the model's 


strategic weight from /model holding as ofthe start date. 


The initial asset size. If excluded, defaults to 1000. 


If true, show the asset sizes from the backtest. If excluded, defaults to true. 


If true, show the trades from the backtest. If excluded, defaults to true. 
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= Parameter Description 

A 

= holdings If true , show the holdings from the backtest. If excluded, defaults to true. 
boolean 
stats If true , show risk and return statistics from the backtest. If excluded, defaults to 
boolean true. 


Example Response 


"asset sizes": { 
"2016-12-01T00:00:00": 1000, 
"2016-12-02T00:00:00": 998.6022625755537, 
"2016-12-05T00:00:00": 1004.3918279210744 


bo 
"trades": | 

{ 
"date": "2016-12-05T00:00:00", 
"ticker": "GOOGL", 
"signal": "SELL", 
"amount": 0.00039250387412376186, 
"type": 2 

bo 

d 
"date": "2016-12-05T00:00:00", 
"ticker": "CSCO", 
"signal": "BUY", 
"amount": 0.0013502458022483788, 
"type": 2 

bo 

{ 
"date": "2016-12-05T00:00:00", 
"ticker": "MCD", 
"signal": "BUY", 
"amount": 0.0001361108332734451, 
"type": 2 

bo 

T 


"date": "2016-12-05T00:00:00", 
"ticker": "WMT", 
"signal": "SELL", 
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"amount": 0.0010938527613980065, 


NAV III 


"type": 2 
} 
l 
"holdings": [ 
{ 
"date": "2016-12-02T00:00:00", 
"tickers": [ 
"GOOGL", 
"CSCO"; 
"MCD", 
"WMT" 
L 
"weights": [ 
0.25039250387412376, 
0.24864975419775162, 
0.24986388916672655, 
@.251093852761398 
], 
"amount": | 
250.04252090065808 , 
248 . 30220713073004, 
249.51464505782053, 
250.742889486345 
] 
bo 
T 


"date": "2016-12-05T00:00:00", 
"tickers": [ 
"GOOGL", 
"CSCO", 
"MCD", 
"WMT" 
L 
"weights": [ 
0.2530329073979014, 
0.2509383051693015, 
0.2507662014695168, 
0.24526258596328018 
L 
"amount": [ 
254 .14418438556214, 
252.0403830244111, 
251.8675234747924, 
246. 33973703630863 
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= } 
z 1, 
= "stats": { 
"cumulative return": 0.004391827921074398, 
"annualized return": 0.7331968693633459, 
"annualized volatility": 0.08076823639707757 
} 
} 
RESPONSE 
Field Description 
asset sizes The asset size per day, beginning on the start date , for the given 
time period. 
trades Rebalancing signals for the given model. 
date The date of the signal. 
ticker The ticker of the security. 
signal The signal, either BUY or SELL. 
amount The amount of the trade. 
type The type of trade signal. 1 = period-based, 2 = drift-based, and 4 = 
downside protection. 
holdings The model's composition by date. 
date The date for the holding details. 
tickers The tickers of the holdings. 
weights The weights of the holdings, represented on a percentage basis. 
amount The total value for each security. 
stats Model metrics for the duration of the backtest. 
cumulative return The cumulative return. 


https://www.hydrogenplatform.com/docs/proton/v1/#Introduction 409/440 


8/3/23, 5:09 PM 


zi 
z 


Field 
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Description 


annualized return The annualized return 


annualized volatility The annualized standard deviation of returns. 


NUCLEUS DATA DEPENDENCIES 


* Model 
e Model Holding 
* Security 


« Security Price 


Monte Carlo 


This service extrapolates the future value of a hypothetical investment account via a random walk Monte 
Carlo. Future values are approximated by simulating individual periods of portfolio growth based on samples 
derived from the given historical performance and volatility portfolio attributes, in conjunction with ongoing 


cash inflows or outflows (which occur at the end of each period) in the simulated account. The return samples 


are stochastic; they assume portfolio returns are distributed normally, and are chained together in a random 


walk sequence. 


HTTP REQUEST 


POST /monte_carlo 


Example Request 


curl -X POST 


-H "Authorization: Bearer «access token>" \ 


-H "Content-Type: application/json" \ 


-d '( 
"cf": [[100,10]], 
"init bal": 1000, 
"ret mod": [60], 
"mu": [0.05], 


"sigma": [0.06], 


n 


: 1000, 


"remove outliers": false, 
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"p": [50], 


NAV Ill 


"result type": 


"min bal": [60], 


Hydrogen Proton API Reference 


"median", 


"max bal": [4000], 
"min sample": [60], 


"max sample": [0.15] 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/monte carlo" 


ARGUMENTS 


Parameter 


cf 


array, required 


mu 


array, conditional requirement 


sigma 


array, conditional requirement 


ret mod 


array 


init bal 


float, conditional requirement 


n 


integer 


Description 


The cash flows to occur during the simulation. This parameter is an array 
containing sub-arrays with 2 elements. The first element of each sub-array 
is a cash flow amount, and the second is a time period duration. Example: 
[[100.00,10], [250.00,15]]. This example indicates cash flows of 
100.00 will take place for 10 consecutive time periods, followed by cash 
flows of 250 for 15 periods (for a total of 25 time periods). Cash flows of 0 
must be defined explicitly. 


The periodic mean portfolio return. The length of the array must be less 
than or equal to the number of time periods present in cf . If itis less, 
values will be conformed to the number of time periods. For example, 
[0.04, 0.06] would result in an implied mu of [0.04, 0.04, 0.06, 
0.06] for a simulation that spans four time periods. 


The periodic portfolio standard deviation. The length of the array must be 
less than or equal to the number of time periods present in cf If it is less, 
values will be conformed to the number of time periods. Values must be 
greater than O. 


A periodic return modifier. Use this value to adjust the randomly generated 
return for each period of the simulation on an absolute basis. For example, 
to reflect a fee of 1% taken out each period, use [-0.01] . If excluded, 
defaults to [0] . 


The initial investment at time zero. If excluded, defaults to 100 . 


The number of simulations to run. Larger values will increase the execution 


time of the service. The maximum acceptable value is 10000 . If excluded, 
defaults to 1000 . 
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Parameter 


remove_outliers 


boolean 


result_type 
string 


p 
array 


min_bal 


array 


max_bal 


array 


min_sample 


array 


max_sample 


array 


use proxy data 


boolean 


market data source 


string 


Hydrogen Proton API Reference 


Description 


If true , remove outlying results. If true , outlier analysis is performed on 
a median absolute deviation (MAD) basis, at the 2.5 threshold. If excluded, 
defaults to false. 


The type of simulation results to display in the output. Value may be raw, 
mean, median, tens,or custom. raw returns all simulation results; 
mean returns the average simulation result; median returns the median 
simulation result; tens return the 10th, 20th, 30th, 40th, 50th, 60th, 70th, 
80th, and 90th percentile simulation results; custom returns results for the 
percentile(s) defined in p. For example, [30, 50, 78] would return the 
30th, 50th, and 70th percentiles. If excluded, defaults to raw. 


Custom result percentile(s). If excluded, defaults to [50]. 


A lower bound to enforce on the periodic balance. Each item in the array 
corresponds to a period in the simulation. If the length of the array is less 
than the number of simulation periods, it is conformed to the appropriate 
length by persisting the final value in the array. 


An upper bound to enforce on the periodic balance. Each item in the array 
corresponds to a period in the simulation. If the length of the array is less 
than the number of simulation periods, it is conformed to the appropriate 
length by persisting the final value in the array. 


A lower bound to enforce on the randomly sampled periodic return. Each 

item in the array corresponds to a period in the simulation. If the length of 
the array is less than the number of simulation periods, it is conformed to 
the appropriate length by persisting the final value in the array. 


An upper bound to enforce on the randomly sampled periodic return. Each 
item in the array corresponds to a period in the simulation. If the length of 
the array is less than the number of simulation periods, it is conformed to 
the appropriate length by persisting the final value in the array. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
sourced from Nucleus Security Price. When value is integration, 
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Parameter 


account id 
UUID, conditional requirement 


aggregation account id 


UUID, conditional requirement 


allocation id 


UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


frequency interval 


string 


create log 


boolean 


Hydrogen Proton API Reference 


Description 


security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive mu, sigma, and init bal. If 
mu or sigma is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus aggregation account used to derive mu, sigma, and 
init bal.lf mu or sigma is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus allocation used to derive mu, sigma,and init bal. 
If mu or sigma is not provided, one of account id, 

aggregation account id, allocation id, model id,or 
portfolio id is required. 


The ID of a Nucleus model used to derive mu, sigma, and init bal If 
mu or sigma is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus portfolio used to derive mu, sigma, and init bal.lf 
mu or sigma is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The periodicity to convert daily values to when deriving mu and sigma 
from Nucleus via an account id, aggregation account id, 
allocation id, model id,or portfolio id. When mu are sigma 
are provided in the raw request, this parameter has no impact. Must be one 
of year, quarter, month, week, or day. Defaults to year. 


If true, a record of this Proton request URL, request body, response body, 
and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit log id willbe returned in the Proton 
response. Defaults to false. 
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1150.7407772024958, 
1323.0962376032248, 
1490.070327954984, 
1672.015451231377, 
1863.3772622510578, 
2066.324013845525, 
2275.2452616749324, 
2501.7737472360695, 
2744.753718748225, 
2993.112513070986 


Description 


Example Response 
d 
"sims": 
[ 
1000, 
] 
] 
} 
RESPONSE 
Field 
sims 


audit log id 


A collection of Monte Carlo results. If result type = raw, this returns multiple sets of 
results, defined by n. If result type = custom, this returns the results in the order 
defined by p. If result type = tens, this returns the results in the order of 10, 20, 
30, 40, 50, 60, 70, 80, 90. If result type - mean or median only one array of results 


will be returned. 


The unique id of the audit log record created in Electron. Only returned when 


create log = true. 


NUCLEUS DATA DEPENDENCIES 


e Security 


e Account 


e Portfolio 


Security Price 


e Portfolio Holding 


e Portfolio Asset Size 


e Model 
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* Allocation 
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e Allocation Composition 

* Aggregation Account 

« Aggregation Account Holding 
* Aggregation Account Balance 


e 


Only one of account id, aggregation account id, allocation id, model id,and portfolio id 


should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Portfolio What-If 


As clients' wants and needs change, it is useful to evaluate shifts in a portfolio's makeup. This tool considers 
the effect of “what-if’ portfolio composition changes such as adding, removing, reducing, or increasing various 
positions in a portfolio. This can help a client make decisions around which securities to buy or sell, or help a 
wealth manager assess portfolio composition over time. The analysis between the current and altered 
portfolios is done on the basis annualized historical return and annualized historical standard deviation. 


HTTP REQUEST 


POST /portfolio what if 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" ^ 
-H "Content-Type: application/json" ^ 
-d '( 
"current portfolio tickers": | 
Devas, 
"PFE", 
"JNJ" 
L 
"current portfolio weights": [ 
0.20, 
0.20, 
0.60 
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al Gh), Gua 
"PFE", 
INT" 


IF 
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"altered portfolio tickers": [ 


"altered portfolio weights": [ 


0.30, 
0.30, 
0.40 


IF 


"start date": "2017-01-01", 
"end date": "2018-12-31", 
"use proxy data": false 


)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/portfolio what if" 


ARGUMENTS 


Parameter 


current portfolio tickers 


array, conditional requirement 


current portfolio weights 


array, conditional requirement 


altered portfolio tickers 


array 


altered portfolio weights 


array, required 


start date 
date 


end date 
date 


use proxy data 


boolean 


Description 


Current portfolio tickers, referencing securities defined in the Nucleus 
API. 


Current portfolio weights, corresponding to 


current portfolio tickers . Must sumto 1.0. 


Altered portfolio tickers, referencing securities defined in the Nucleus 
API. Defaults to current portfolio tickers. 


Altered portfolio weights, corresponding to 
altered portfolio tickers . Must sum to 1.0. 


Start date used for ticker price history. Defaults to earliest common date 
among current portfolio tickers and 
altered portfolio tickers prices. 


End date used for ticker price history. Defaults to latest common date 
among portfolio tickers and altered portfolio tickers 
prices. 


If true, incorporate proxy price data as defined at the Security level in 
the Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 
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market_data_source 
string 


account_id 


UUID, conditional requirement 


aggregation_account_id 
UUID, conditional requirement 


allocation_id 


UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


create log 
boolean 


Hydrogen Proton API Reference 


Description 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price 
data is sourced from Nucleus Security Price. When value is 
integration, security price data is sourced from a configured 
Integration Market Data vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive 

current portfolio tickers and current portfolio weights. If 
current portfolio tickers or current portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

current portfolio tickers and current portfolio weights. If 
current portfolio tickers or current portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus allocation used to derive 

current portfolio tickers and current portfolio weights. If 
current portfolio tickers or current portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive 

current portfolio tickers and current portfolio weights. If 
current portfolio tickers or current portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive 

current portfolio tickers and current portfolio weights. If 
current portfolio tickers or current portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


If true, a record of this Proton request URL, request body, response 
body, and Nucleus UUID(s), where applicable, will be stored in Electron 
as an audit log, and the resulting audit log id will be returned in the 
Proton response. Defaults to false. 
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a Example Response 
2 
{ 
"annualized_return": { 
"current portfolio": 0.158543872616828, 
"altered portfolio": 0.13392921668177515, 
"delta": -0.024614655935052854 
bo 
"annualized volatility": { 
"current portfolio": 0.005478420111416463, 
"altered portfolio": 0.005193612691605431, 
"delta": -0.00028480741981103206 
} 
} 
RESPONSE 
Field Description 


annualized return 


current portfolio 


altered portfolio 


delta 


annualized volatility 


current portfolio 


altered portfolio 


delta 


audit log id 
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Annualized return information for the current and altered portfolios. 


Current portfolio’s annualized return. 


Altered portfolio’s annualized return. 


Raw difference in annualized return between the current and altered 


portfolios. 


Annualized portfolio standard deviation. 


Current portfolio’s annualized standard deviation. 


Altered portfolio’s annualized standard deviation. 


Raw difference in annualized standard deviation between the current and 
altered portfolios. 


The unique id of the audit log record created in Electron. Only returned when 
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Field Description 


NAV Ill 


create_log = true. 


NUCLEUS DATA DEPENDENCIES 


* Security 

* Security Price 

* Account 

* Portfolio 

e Portfolio Holding 

e Model 

e Model Holding 

* Allocation 

* Allocation Composition 
e Aggregation Account 


« Aggregation Account Holding 


e 


Only one of account id, aggregation account id, allocation id, model id,and portfolio id 


should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Scenario Analysis 


When assessing a portfolio, it is useful to simulate its response to a series of external factors. Scenario 
Analysis provides a statistical estimate of the impact that a combination of external movements may have on a 
portfolio's rate of return, based on a multivariate regression model that considers historical price behavior. In 
order to support many types of real-world situations, this tool accounts for the magnitude, direction, and 
duration of a given change (e.g. a 1096 upward movement over a period of 2 weeks). It also supports the 
ability to reflect a lag between the movement of each factor and the portfolio (e.g. the portfolio is impacted 3 
days after the factor movement). The resulting analysis can be helpful in comparing the economic exposures 
of different portfolios. 


HTTP REQUEST 


POST /scenario analysis 


Example Request 
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a curl -X POST -H "Authorization: Bearer «access token»" \ 
= -H "Content-Type: application/json" \ 
-d '( 
"portfolio tickers": [ 
"HD", 
"PG", 
"EBAY", 
"NVDA" 
L 
“portfolio weights": [ 
0.25, 
0.25, 
0.25, 
0.25 
L 
“frequency interval": "month", 
"scenario": [ 
1 
"ticker": "VNQ", 
"change amount": 0.02, 
"change duration": 1, 
"lag": © 
J 
{ 
"ticker": "GLD", 
"change amount": -0.05, 
"change duration": 3, 
"lag": 1 
) 
L 
"start date": "2015-08-11", 
"end date": "2016-12-31", 
"trading days per year": 252, 
"use proxy data": false 
)' "https://[sandbox][api].hydrogenplatform.com/proton/vi/scenario analysis" 
ARGUMENTS 
Parameter Description 


portfolio tickers Portfolio tickers, referencing securities defined in the Nucleus API. 


array, conditional requirement 
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Parameter 


portfolio weights 
array, conditional requirement 


frequency interval 


float, required 


scenario 


map, required 


ticker 


string, required 


change amount 


float, required 


change duration 


integer, required 


lag 
integer, required 


start date 
date 


end date 
date 


trading days per year 


integer 
use proxy data 


boolean 


market data source 


string 


Hydrogen Proton API Reference 


Description 


Portfolio weights, corresponding to portfolio tickers . Must sum to 
1.0. 


Unit of time associated with change duration and lag. Must be one of 


year, quarter, month, week, or day. 


A scenario to analyze, defined as a series of hypothetical price movements 


for securities, indices, or other instruments. 


Ticker representing the factor, referencing a security defined in the Nucleus 
API. 


A percentage price change, represented in decimal format. Value can be 
positive or negative. 


Number of time periods over which change amount is to take place, 
where each period represents frequency interval. 


Number of time periods between the factor signal and the portfolio's 
response to that signal, where each period represents 

frequency interval. For example, a value of 3 indicates that the 
portfolio responds 3 periods after the factor moves. Value cannot be 
negative. 


Start date used for ticker price history. Defaults to earliest common date 
among portfolio tickers and scenario ticker prices. 


End date used for ticker price history. Defaults to latest common date 


among portfolio tickers and scenario ticker prices. 


The number of days per year for which a portfolio is subject to market 
fluctuation. Defaults to 252. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 
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account_id 


UUID, conditional requirement 


aggregation_account_id 


UUID, conditional requirement 


allocation_id 


UUID, conditional requirement 


model id 


UUID, conditional requirement 


portfolio id 
UUID, conditional requirement 


create log 


boolean 


e 
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Description 


The ID of a Nucleus account used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

portfolio tickers and portfolio weights. If portfolio tickers 
or portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 
portfolio id is required. 


The ID of a Nucleus allocation used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


If true, a record of this Proton request URL, request body, response body, 
and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit log id willbe returned in the Proton 
response. Defaults to false. 


Due to the relationship between change duration, lag, start date,and end date, some input 


configurations may lead to an insufficient amount of price data. In these cases, the analysis will not run and 


you will receive a 400 status. 


Example Response 
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0.010304645392564492, 
[ 


"t statistic": 4.770856786757572, 


coefficient": 0.8023214304210411 


"t statistic": 0.6448259002724069, 


coefficient": 0.1148356643171266 


a ( 
zZ "portfolio_impact": 
"scenario results": 
{ 
"ticker": "VNQ", 
"regression _ 
bo 
d 
“ticker”: "GLD"; 
"regression_ 
} 
] 
} 
RESPONSE 
Field 


portfolio_impact 


scenario_results 


ticker 


t_statistic 


regression_coefficient 


audit_log_id 


NUCLEUS DATA DEPENDENCIES 


e Security 
e Security Price 


e Account 


Description 


Expected impact of scenario factors on the portfolio’s return. The 
associated unit of time is the base unit indicated by 
frequency_interval in the request (for example, week = 1 week). 


Underlying results for each scenario factor, including the fields shown 
below. 


Ticker to indicate the factor. 


Raw t-statistic from the regression analysis, typically used to determine 
statistical significance of regression coefficient. 


Statistical relationship between the ticker return and the portfolio 


return. 


The unique id of the audit log record created in Electron. Only returned 


when create_log = true. 
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* Portfolio Holding 

* Model 

e Model Holding 

* Allocation 
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e Allocation Composition 
* Aggregation Account 


* Aggregation Account Holding 


e 
Only one of account id, aggregation account id, allocation id, model id,and portfolio id 


should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Sensitivity Analysis 


When assessing a portfolio, simulating its response to an external factor can give greater insight into the 
portfolio's exposure. Sensitivity Analysis provides a statistical estimate of the impact that an external 
movement may have on a portfolio's rate of return, based on an ordinary-least-squares linear regression 
model that considers historical price behavior. In order to support many types of real-world situations, this tool 
accounts for the magnitude, direction, and duration of a given change (e.g. a 10% upward movement over a 
period of 2 weeks). It also supports the ability to reflect a lag between the movement of the factor and the 
portfolio (e.g. the portfolio is impacted 3 days after the factor movement). The resulting analysis can be helpful 
in comparing the economic and risk exposures of different portfolios. 


HTTP REQUEST 


POST /sensitivity analysis 


Example Request 


curl -X POST -H "Authorization: Bearer «access token»" \ 
-H "Content-Type: application/json" \ 
-d '( 
"portfolio tickers": [ 
"HD", 
"PG", 
"EBAY", 
"NVDA" 
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“portfolio weights": [ 

0,25; 

0.25; 

0.25, 

0.25 
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L 
"frequency interval": "day", 
“sensitivity factor": ( 
"ticker": "AGG", 
"change amount": -0.05, 
"change duration": 3, 
"lag": 0 
D 
"start date": "2015-08-11", 
"end date": "2016-12-31", 
"trading days per year": 252, 
"use proxy data": false 


)' "https://[sandbox][api].hydrogenplatform.com/proton/v1/sensitivity analysis' 


ARGUMENTS 


Parameter Description 


portfolio tickers Portfolio tickers, referencing securities defined in the Nucleus API. 


array, conditional requirement 


portfolio weights Portfolio weights, corresponding to portfolio tickers . Must sum to 


array, conditional requirement 1.0. 


frequency interval Unit of time associated with change duration and lag.Must be one of 
string, required year, quarter, month, week, or day. 
sensitivity factor A factor to analyze, defined as a hypothetical price movement for a security, 
map, required index, or other instrument. 
ticker Ticker representing the factor, referencing a security defined in the Nucleus 
string, required API. 
change amount A percentage price change, represented in decimal format. Can be positive 
float, required or negative. 
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Parameter 


change duration 


integer, required 


lag 


integer 


start date 
date 


end date 
date 


trading days per year 


integer 
use proxy data 


boolean 


market data source 
string 


account id 


UUID, conditional requirement 


aggregation account id 


UUID, conditional requirement 


allocation id 


UUID, conditional requirement 


Hydrogen Proton API Reference 


Description 


Number of time periods over which change amount is to take place, 
where each period represents frequency interval. 


Number of time periods between the factor signal and the portfolio's 
response to that signal, where each period represents 

frequency interval. For example, a value of 3 indicates that the 
portfolio responds 3 periods after the factor moves. Defaults to 0, and 
cannot be negative. 


Start date used for ticker price history. Defaults to earliest common date 
among portfolio tickers and sensitivity factor ticker prices. 


End date used for ticker price history. Defaults to latest common date 


among portfolio tickers and sensitivity factor ticker prices. 


The number of days per year for which a portfolio is subject to market 
fluctuation. Defaults to 252. 


If true , incorporate proxy price data as defined at the Security level in the 
Nucleus API. Proxy data is merged with base security data to form a 
continuous price history. Defaults to false. 


Source of security price data to be used in the analysis. Value may be 
nucleus or integration. When value is nucleus , security price data is 
sourced from Nucleus Security Price. When value is integration, 
security price data is sourced from a configured Integration Market Data 
vendor. Defaults to nucleus. 


The ID of a Nucleus account used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus aggregation account used to derive 

portfolio tickers and portfolio weights.lf portfolio tickers 
or portfolio weights is not provided, one of account id, 
aggregation account id, allocation id, model id,or 


portfolio id is required. 


The ID of a Nucleus allocation used to derive portfolio tickers and 


portfolio weights. If portfolio tickers or portfolio weights is 
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Parameter 


model id 


UUID, conditional requirement 


portfolio id 


UUID, conditional requirement 


create log 


boolean 


e 


Hydrogen Proton API Reference 


Description 


not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


The ID of a Nucleus model used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 


allocation id, model id,or portfolio id is required. 


The ID of a Nucleus portfolio used to derive portfolio tickers and 
portfolio weights.lf portfolio tickers or portfolio weights is 
not provided, one of account id, aggregation account id, 
allocation id, model id,or portfolio id is required. 


If true, a record of this Proton request URL, request body, response body, 
and Nucleus UUID(s), where applicable, will be stored in Electron as an 
audit log, and the resulting audit log id will be returned in the Proton 
response. Defaults to false. 


Due to the relationship between change duration, lag, start date, and end date, some input 


configurations may lead to an insufficient amount of price data. In these cases, the analysis will not run and 


you will receive a 400 status. 


Example Response 


i 
"portfolio impact": 0.03466700648259927, 
"t statistic": -2.401636667959841, 
"margin of error": 0.02829157510133723 
} 
RESPONSE 
Field Description 


portfolio impact Expected impact of sensitivity factor on the portfolio's return. The 


associated unit of time is the base unit indicated by frequency interval in the 
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Field Description 


NAV Ill 


request (for example, week = 1 week). 


t_statistic Raw t-statistic from the regression analysis, typically used to determine statistical 
significance of the regression coefficient. 


margin_of_error Estimated margin of error pertaining to portfolio impact at a 95% confidence 
level. 
audit log id The unique id of the audit log record created in Electron. Only returned when 


create log = true. 


NUCLEUS DATA DEPENDENCIES 


* Security 

* Security Price 

* Account 

e Portfolio 

e Portfolio Holding 

* Model 

e Model Holding 

* Allocation 

* Allocation Composition 
* Aggregation Account 

* Aggregation Account Holding 


e 
Only one of account id, aggregation account id, allocation id, model id,and portfolio id 
should be provided. An error will be thrown if multiple Nucleus data entities are referenced in a single request. 


Appendix 


This appendix contains additional information to elaborate on the underlying algorithm methodology. 
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Financial Health Check 


Applicable Proton Services 


e POST /financial health check 


Methodology 


The Financial Ratio Calculation results are compared to the Ideal Ratio. If the Financial Ratio is the Ideal Ratio 
Result or higher, the Ratio Test Result is marked as Pass. If the Financial Ratio is outside of the Ideal Ratio 
Result or lower, the Ratio Test Result is marked as Fail. 


The Percentile Scale is calculated in the following way: 


e [fa Calculation Result is the Ideal Result or higher, the Percentile Scale returns 100 
e [fa Calculation Result is less than the the Ideal Result, the Percentile Scale returns = "Calculation Result" / 
"Ideal Result" 


Notes & Considerations 


Ideal Results & Ideal Direction of Outputs: 


. liquidity ratio expenses: x >= 250% , Higher 

. liquidity ratio liabilities: x >= 10%, Higher 
. current ratio: x >= 50% , Higher 

. savings ratio gross: x >= 10% , Higher 

. savings_ratio_net:x >= 10% , Higher 


D O BB O N = 


. asset allocation ratio:x>=15% , Higher 


References 


i. https://pdfs.semanticscholar.org/269d/5f90e8ce1951d74c61e2a3f8ed116c4eb021.pdf 
ii. https://www.afcpe.org/assets/journals/vol 13.pdf 
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Goals Framework 


Goals are described in terms of net purchasing power. This means that certain variables, including 
monetary inflation and taxes paid on the redemption of capital, are accounted for explicitly. For example, a 
target goal of 100 may correspond to an implied outcome of 125 if the capital is assumed to be taxed at a 
rate of 20% upon redemption. The purpose of this mechanism is to better reflect real-world purchasing 
power through the culmination of the goal horizon. 


All goals are classified as either accumulation or decumulation. Accumulation goals are defined by a target 
amount of capital in the future, assumed to be redeemed in full upon termination of the goal horizon. 
Decumulation goals are defined by redeeming a target amount of capital periodically over a horizon, which 
may also include an accumulation phase. 


Configurations that involve contributions of capital (via an initial investment sum or an ongoing recurring 
deposit, for example) will prioritize a minimization of the present value of cash outlays. This built-in engine 
assumes that goal achievement with minimal cash expenditure is most desirable, ceteris paribus. 


Goal achievement probabilities are extrapolated via Monte Carlo analysis. For more information on the 
Monte Carlo methodology, refer to the Monte Carlo Appendix section of this appendix. The distribution of 
outcomes generated by this process allows for an assessment of the likelihood that a goal will be attained. 
Please note that such goal probabilities are uncertain by nature, and repeating this type of simulation-based 
analysis may not yield precisely the same results. 


Simulation results generated in the goals framework are returned on a yearly basis. The first item always 
indicates the investment value at t0, such that each simulation result for a 10-year goal horizon will contain 
11 observations (t0 plus one observation for each year in the goal horizon). 


Goal achievement indicators are derived from the relationship between goal achievement probability and a 
desired confidence target. Confidence targets serve as the basis for a percentile analysis of Monte Carlo 
outcomes, in which outcomes below the ((1 — c) * 100)th percentile, where c is the confidence target on a 
scale from 0 to 1, are excluded as a left-tail margin. If the confidence target is not satisfied, this is reflected 
by a goal probability that is less than the confidence target. 


Because individual outcomes are binary in nature, the framework supports optional goal deviation 
thresholds in order to promote robustness. Thresholds may be set on an absolute basis or a percentage 
basis, and serve as an acceptable error margin on the nominal goal amount. For example, a goal of 10,000 
modified with a 0.5096 acceptable deviation threshold indicates that outcomes as low as 9,950 will be 
considered affirmative for goal achievement. 


For decumulation goals, deposits are assumed to stop at the end of the accumulation horizon. 


Goal Allocation Appendix 


Applicable Proton Services 


POST /goal accumulation/allocation 
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e POST /goal_decumulation/allocation 


Methodology 


For the “risk” allocation_priority, the chosen portfolio is based on the defined risk_score (see Risk Allocation for 
more information). For the “goal” allocation_priority, the engine searches through a series of potential goal 

plan configurations in which the portfolio risk and return change while the initial investment amount, periodic 
deposit amount, goal horizon, and target goal amount are held constant. The lowest risk portfolio that projects 
to meet the goal confidence target is chosen. 


Notes & Considerations 


e Fora “goal” allocation priority, the minimal risk portfolio that satisfies the goal will be chosen, but the 
risk score parameter is not considered explicitly. This may lead to an investor being allocated to a portfolio 
that is riskier than suitable for a given risk appetite. 

e Fora “risk” allocation priority, risk appetite is the driving factor, and this may lead to a goal not being 
successfully achieved. 


Goal Recommendation Appendix 


Applicable Proton Services 


e POST /goal_accumulation/recommendation 
e POST /goal decumulation/recommendation 
e POST /goal accumulation/status 

e POST /goal decumulation/status 

e POST /goal accumulation/allocation 


e POST /goal decumulation/allocation 


Methodology 


The process of generating a recommendation entails constructing a set of potential new goal plans by 
changing specific plan components and holding others constant. The engine determines a minimum viable 
outcome by searching through the universe of potential goal plans. 


“Recurring” recommendations leverage the introduction of a new periodic recurring deposit, without altering 
the initial investment amount, the goal horizon, the portfolio attributes, or the target goal amount. An available 
domain is constructed based on the dep min and dep max parameters, and discrete values in the domain 
serve as the basis of a new goal plan universe. The smallest periodic deposit that projects to meet the goal 
confidence target is recommended. 


“One-time” recommendations leverage the introduction of a new one-time deposit, without altering the periodic 
deposit amount, the goal horizon, the portfolio attributes, or the target goal amount. One-time deposits are 
attributed at time zero, effectively increasing the initial investment amount component of the goal plan. An 


available domain is constructed based on the inv min and inv max parameters, and discrete values in the 
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domain serve as the basis for a new goal plan universe. The smallest one-time deposit that projects to meet 
the goal confidence target is recommended. 
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“Combo” recommendations leverage the introduction of a new one-time deposit as well as a new periodic 
deposit, without altering the goal horizon, the portfolio attributes, or the target goal amount. One-time deposits 
are attributed at time zero, effectively increasing the initial investment amount component of the goal plan. An 
available domain is constructed based on the dep_min, dep_max, inv_min, and inv_max parameters. The 
permutation of a one-time deposit and recurring deposit with the smallest present value that projects to meet 
the goal confidence target is recommended. 


“Horizon” recommendations leverage the introduction of a new accumulation horizon, without altering the 
initial investment amount, the periodic deposit amount, the portfolio attributes, or the target goal amount. An 
available domain is constructed by incrementing the original goal accumulation horizon forward, up to a 
maximum of 32 years above the original value. The shortest accumulation horizon that projects to meet the 
goal confidence target is recommended. 


Notes & Considerations 


e “Combo” recommendations, the domain of potential goal plans consists of all permutations of the potential 
one-time deposits and the potential recurring deposits. 


Goal Tracking Appendix 


Applicable Proton Services 


e POST /goal_accumulation/status 
e POST /goal_decumulation/status 


Methodology 


The current goal plan configuration is first used to execute a Monte Carlo simulation (see Monte Carlo 
Appendix section for more information). The result determines whether or not the goal is currently on track. 
For accumulation goals, in which the goal is defined by a total accumulation amount at the end of the 
accumulation horizon, final outcomes from the simulations must be greater than or equal to the target goal 
amount in order to be considered successful. For decumulation goals, in which the goal is defined by a 
periodic withdrawal amount over the course of the decumulation horizon, final outcomes from the simulations 


must be greater than zero in order to be considered successful. The goal probability (p) is computed as: 
p = number of successes / number of simulations 


The boolean tracking status is reported as true if p is greater than or equal to the user-defined confidence 
target, and reported as false if p is less than the user-defined confidence target. 


Goal achievement scores are calculated by comparing p to the confidence target: 


goal achievement score = p / confidence target 
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Goal progress is determined by comparing the current amount in the goal configuration to the target goal 
amount. For accumulation goals, this is defined as: 
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goal progress = current investment amount / target accumulation amount 


For decumulation goals, a feasible decumulation amount is first estimated by lowering the target goal amount 
until the confidence target is satisfied. This answers the question: “If the decumulation horizon started today, 
what amount could be successfully withdrawn from the current balance over the desired decumulation 
horizon?” This value is used as the basis of the goal progress calculation, as follows: 


goal progress = feasible decumulation amount / target decumulation amount 


Notes & Considerations 


e Goal achievement scores are normalized onto a 0-100 scale, where 0 indicates minimal likelihood of goal 
achievement and 100 coincides with an affirmative tracking status. 
e |f the recommend parameter is true, a recommendation will only be generated if the tracking status is 


negative. 


Portfolio Construction 


Mean-Variance Optimization Appendix 


Applicable Proton Services 


* POST /mvo 
* POST /risk allocation 
e POST /goal accumulation/allocation 


e POST /goal decumulation/allocation 


Methodology 


The model consumes an expected return for each security and the covariance relationships among all 
securities, which are derived directly from the security price data. Expected return is defined as the mean of a 
given security's price distribution across the available data, while the covariance relationship between 
securities y and z is defined standardly as: 


cov(y,z) = i=1n(y - y)(z - n - 1 


The optimization process leverages a standard convex optimization protocol that solves problems via Second 
Order Cone Programming (SOCP)!. Problems are structured with three primary elements: an Objective, a 
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Variable, and Constraints. Here, the Objective is defined as a maximization of the portfolio mean return or a 
minimization of portfolio variance, the Variable is defined as an array of security weights, and the Constraints 
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change based upon user input but include an upper or lower bound restriction on the portfolio’s return or 
variance. Other user-defined constraints include: 


e w_config - A series of weight constraints by security type: 
o Major securities are intended to be securities with more lenient weight thresholds. 
o Minor securities are intended to be securities with tighter weight thresholds. 
o Cash securities are constrained to a constant weight. 
e w asset config - A series of weight constraints by security asset class: 
o Asset class constraints set a maximum weight threshold that applies to the cumulative sum of 
weights across securities of a given asset class. 
e min assets - The minimum number of securities to be included in an optimized portfolio (formally defined as 
the number of non-zero weights, excluding cash). 


For efficient frontier optimization, a series of problems is solved in the following order: 


1. A problem with an Objective to minimize portfolio variance. 
o This derives the portfolio with the lowest possible risk, which serves as the frontier domain's lower 
bound. 
2. A problem with an Objective to maximize portfolio return. 
o This derives the portfolio with the highest possible return, which serves as the frontier domain's upper 
bound. 
3. A problem with an Objective to maximize portfolio return for each risk value in the frontier domain, in 
ascending order. 
o Variance values are chosen along a logarithmic path between the variance derived from (1) and the 
variance derived from (2). 
o For each problem, the chosen variance is issued as an upper bound Constraint. 
o To maintain integrity of the frontier shape, new ascending solutions are only recorded if the optimal 
portfolio return is higher than previous portfolio returns. 


For target portfolio optimization, a single problem is configured as follows: 


e When targeting a risk value, the objective is set to maximize portfolio return and an upper bound constraint 
is placed on the portfolio variance. 

e When targeting a return value, the objective is set to minimize portfolio variance and a lower bound 
constraint is placed on the portfolio return. 


Notes & Considerations 


e Problem convexity is enforced via Disciplined Convex Programming (DCP) criteria’. 

e Minimum weight constraints are joined with zero to form a binary constraint. Hence, the weight w is 
allowable if w = 0 or w 2 min, but not if O < w < min. 

e An error will be raised if the problem cannot be solved. This commonly occurs in two cases: 
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o When the security price data input into the model is incorrect or contains a very small amount of data 
points 
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o When the user-defined constraints are too restrictive 
e A maximum of 30 portfolios will be generated on the efficient frontier. 


References 


i. https://web.stanford.edu/~boyd/cvxbook/bv_cvxbook.pdf 
ii. http://dcp.stanford.edu/ 


Portfolio Management 


Rebalancing Appendix 


Applicable Proton Services 


e POST /rebalancing signal 


Methodology 


This service generates trade signals to strategically rebalance a model portfolio, with support for three types of 
rebalancing: period-based, drift-based, and Downside Protection. Period-based rebalancing generates signals 
at the beginning of each time period with predefined frequency. Drift-based rebalancing generates signals 
when a portfolio holding deviates from its strategic target by a predefined amount. Downside Protection 
generates signals based on the observed risk of portfolio holdings, driven by Hydrogen's proprietary risk 
management algorithm. 


Hydrogen's Downside Protection algorithm has four main goals: 


Limit drawdownsi 


e Reduce volatility and beta 
e Track benchmarks on the upside 
e Achieve superior risk-adjusted returns over the long-term 


The primary driver of Downside Protection is dynamic asset allocation, defined as a rules-based allocation 
strategy that includes responsiveness to market environments. Dynamic asset allocation differs from a passive 
or indexing strategy, which is static and not responsive (periodic or period-based rebalancing notwithstanding). 
Rebalancing within a dynamic framework is conditional rather than pre-determined. This also differs from an 
active strategy that uses forward-looking positions to try to take advantage of future market conditions. 
Dynamic allocations as described here are reactive and not predictive. 
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Hydrogen's methodology utilizes a time-varying version of the CPPI!! framework (called TPPI'"). The time- 
varying portion is the level set for the floor, which changes based on market conditions and governs how 
rebalancing occurs. Based on quantitative risk measures looked at daily in the portfolio, the algorithm moves 
between risky and safe assets. The risky asset is weighted on a scale that ranges from 100% to 0% — 
meaning that the portfolio can be fully invested or fully protected at any given time, and can move up or down 
from each level in between. This allows the algorithm to ladder out of a position as it becomes riskier, and 
ladder in as it becomes less risky, in order to achieve an optimal mix for end-users. 


The framework is extended for entire portfolios rather than for a single risky asset. Instead of looking at the 
portfolio as a whole, the algorithm assesses each holding individually to apply risk management, on a daily 
basis. This aims to achieve three objectives: 


e Set optimal risk thresholds for each asset class. Commodities are much riskier than bonds, so different 
risk thresholds should apply. 

e Limit transactions and transaction costs. By separating a portfolio into buckets, the algorithm avoids 
unnecessary transaction costs and maximizes the benefit of every trade. 

e Maintain portfolio integrity. Each asset class has a strategic weight that acts as an anchor, so a given 
portfolio doesn't get riskier than intended (only less risky, when necessary) and no leverage is ever used. 


Trades are triggered by the ongoing risk of each security in the model portfolio. Risk is assessed based upon 
the moving average current drawdown of a security and standardized onto a 0-100 scale. Downside trading 
occurs in 3 levels, each of which is triggered when the risk assessment value moves across predefined 
thresholds on the risk scale. Each level is associated with a given amount of exposure, which is defined on a 
relative basis as a percentage of the security's strategic weight. For example, a security may have levels of 
7596, 5096, and 2596 exposure triggered at 70, 80, and 90 risk assessment values. If the risk value moves 
from 69 to 71 for a given security, the security in question will be rebalanced to 7596 of its original strategic 
weight. If the risk values drop from 71 back to 69, the security will be rebalanced to 100% of its strategic 
weight. 


This framework can be applied to any type of portfolio — conservative or aggressive, diversified or 
concentrated, ETF-based or stock-based. Please note, using securities that have low liquidity may impede 
portfolio return through higher bid-ask spreads. 


Notes & Considerations 


e Each signal has an indicator for the applicable type of rebalancing: 
o 1 = period-based rebalancing signal 
o 2= drift-based rebalancing signal 
o 4= Downside Protection rebalancing signal 

e One portfolio may have multiple rebalancing types activated. 


References 


i. “Optimal Investment Strategies for Controlling Drawdowns” published in Mathematical Finance, July 1993, 
by Dr. Sanford Grossman and Dr. Zhongquan Zhou, professors at The Wharton School, University of 
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Pennsylvania. 
li. "Dynamic Strategies for Asset Allocation" published in 1988 by Andre Perold of Harvard Business School 
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and Nobel Prize winner William Sharpe. 

iii. “CPPI — constant proportion portfolio insurance: protection with dynamic allocation control” published in 
2006 by Martin Ermini from BNP Paribas. *Enhanced Balanced Portfolios With CPPI Methodologies" published 
in 2008 by Francesco Rossi of Pioneer Investments. 

iv. "A Time-varying Proportion Portfolio Insurance Strategy Based on a CAViaR Approach" published in 2008 
by Benjamin Hamidi, Bertrand Maillet, Jean-Luc Prigent, prominent financial academics in France. 


Risk Scoring 


Risk Score Appendix 


Applicable Proton Services 


e POST /risk score 


Methodology 


Answer values are normalized onto a [0,100] scale based on their relationship to the corresponding 
max answers values. These transformed answer values (x) contribute to the weighted average (wa) as: 


wax = w1x1 + w2x2 ... wnxn 


Notes & Considerations 


e Higher answer values and max answers values are assumed to indicate more appetite for risk. 
e Weights default to be equally weighted. 


Dimensional Risk Score Appendix 


Applicable Proton Services 


e POST /dimensional risk score 


Methodology 


Answer values are first grouped by dimension, and then are normalized onto a [0,100] scale based on their 


relationship to the corresponding max answers values. These transformed answer values (x) contribute to a 
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series of dimensional scores (ds) based on answer weights (aw) as: 
dsx = aw1x1 + aw2x2 ... awnxn 


These dimensional scores are then combined to compute the total weighted score (tws) based on dimensional 
weights (dw) as: 


tws = dw1ds1 + dw2 ds2 ... dwndsn 


Notes & Considerations 


e The framework can handle any number of distinct dimensions. 

e Individual answers may be mapped to one or multiple risk dimensions. 

e When more than one question map to a given dimension, proportional relationships between various 
answer weights serve as the basis for weighting answers within that dimension. 

e |f a given dimension has no answers mapped to it, it is dropped from consideration and any remaining 
values are re-normalized. 


Risk Allocation Appendix 


Applicable Proton Services 


e POST /risk allocation 
e POST /goal accumulation/allocation 


e POST /goal decumulation/allocation 


Methodology 


The risk score parameter, which is scaled from O to 100, is used to conduct a percentile analysis of the 
predefined portfolio risk values. When the target percentile falls between two portfolios, the risk value that is 
closer to the ideal percentile value on an absolute basis is chosen. 


For the “create” allocation method, an efficient frontier domain is constructed based on the constraints defined 
in the opt config parameter. The risk score parameter, which is scaled from 0 to 100, is used to conduct a 
percentile analysis within the domain. A portfolio is then optimized, using the percentile value within the risk 
domain as a risk target (see the Mean-Variance Optimization Appendix section for more information). 


Notes & Considerations 


e The parameters performance and volatility must be defined in /allocation if “select” is chosen. 
« For “select”, the portfolio with the closest match to the risk score will be selected. 
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Backtest Appendix 


Applicable Proton Services 


e POST /rebalancing signal 
e POST /backtest 


Methodology 


At the beginning of each period during the backtest period, the time series data for each security of the 
portfolio model is incremented up to the current date of the analysis. Weights are adjusted based on the 
periodic performance of each security in the portfolio, and asset size updates are computed with a simple 
weighted average of positional performance. Trades are determined via the model's rebalancing type, with the 
trading logic as follows: 


For period-based rebalancing, the current date in the time series is analyzed on an absolute calendar basis. 
Annual period rebalancing to the model strategic weights is triggered if the date passes December 31st of a 
given year. Semiannual period rebalancing to the model strategic weights is triggered if the date passes June 
30th of a given year. Quarterly period rebalancing to the model strategic weights is triggered if the date passes 
March 31st, June 30th, September 30th, or December 31st of a given year. Monthly period rebalancing to the 
model's strategic weights is triggered if the current date's month is greater than the previous date's month. 


For drift-based rebalancing, rebalancing to the model's strategic weights is triggered if any security deviates 
from its strategic weight by a relative amount greater than its user-defined drift threshold. For example, a 1096 
drift factor applied to a security with a 2096 strategic weight is triggered if the floating weight of the security 
falls below 18% or rises above 22%. When drift-based rebalancing is triggered, all securities in the portfolio 
are rebalanced to their respective strategic weights. For more information on downside protection, please see 
the Rebalancing Appendix section. 


Notes & Considerations 


e Drift thresholds are defined on a positional basis, and each portfolio security may have a unique drift factor. 

e For Downside protection rebalancing, when the risk of a security triggers a trade, proceeds from any sale 
are shifted into a designated "safe" security. This safe security is assumed to be something with less risk 
than non-safe securities. 


Monte Carlo Appendix 


Applicable Proton Services 
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e POST /monte carlo 


e POST /goal accumulation/recommendation 
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e POST /goal decumulation/recommendation 
e POST /goal accumulation/status 

e POST /goal decumulation/status 

e POST /goal accumulation/allocation 


e POST /goal decumulation/allocation 


Methodology 


e For each period in the Monte Carlo simulation, the initial balance is applied at time zero. For each 
subsequent period, the following process occurs: 
o A return is sampled from a normal distribution with mu and sigma attributes defined by the user 
o The ret mod value is applied to the sampled return to derive a modified return 
o The modified return is used to calculate a current balance from the previous balance 
o The applicable periodic cash flow is applied to the calculated balance to get the resulting balance for 
the period 
e |f remove outliers is true, an outlier analysis is performed on a median absolute deviation (MAD) basis, at 
the standard 2.5 threshold 
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